# os-com

**Repository Path**: frankPointer/os-com

## Basic Information

- **Project Name**: os-com
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: oscom-optimize
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# osCom

osCom 是一个面向校内办事政策的 DocQA RAG 应用，并提供本地
llama-server 的提示词缓存性能测试页面。

聊天页面中的 `doc_qa` Agent 会根据问题自行决定直接回答、追问，或调用
知识库工具检索政策内容；检索到的证据会交给模型组织最终回复。性能测试页面
提供三种提示词布局，用于观察本地服务在不同前缀稳定性下的表现。

项目只连接 OpenAI 兼容的本地 llama-server，不构建、启动或识别其内部的
Prompt Cache 实现。缓存后端和模型运行参数由使用者启动的 llama-server 决定。

## 前置条件

- Python 3.10 或更高版本
- 一个已启动的、支持 `/v1/chat/completions` 和工具调用的本地 llama-server
- 可供 llama-server 加载的模型文件

## 安装

在项目目录中安装运行依赖：

```bash
cd /path/to/os-com
python -m pip install -r requirements.txt
```

需要运行测试时，再安装开发依赖：

```bash
python -m pip install -r requirements-dev.txt
```

## 配置

从示例配置创建本机配置：

```bash
cp .env.example .env
```

对于已在默认地址启动的 llama-server，只需确认以下配置：

```dotenv
LLM_BASE_URL=http://127.0.0.1:8080/v1
LLM_API_KEY=none
LLM_MODEL=local
```

配置项说明：

| 配置项 | 说明 |
| --- | --- |
| `LLM_BASE_URL` | llama-server 的 OpenAI 兼容 API 地址，必须包含 `/v1`。 |
| `LLM_API_KEY` | API 密钥；本地服务通常可保留为 `none`。 |
| `LLM_MODEL` | llama-server 暴露的模型别名。 |
| `LLAMA_TOOL_URL` | 可选。需要将工具调用请求发送到另一服务时设置；留空则使用 `LLM_BASE_URL`。 |
| `DOC_QA_KNOWLEDGE_PATH` | 可选。政策知识库文件路径，默认是 `data/doc_qa/knowledge.json`。 |

`.env` 和可选的 `.local/env.sh` 都位于项目根目录。启动脚本会先加载
`.local/env.sh`，再加载 `.env`，因此可将 Conda、NPU 驱动等机器相关环境放在
`.local/env.sh`，而将服务地址和项目配置放在 `.env`。

### 启动本地 llama-server

先按照自己的模型和硬件环境启动 llama-server，并保证其模型别名、端口与 `.env`
一致。例如：

```bash
llama-server \
  --model /path/to/model.gguf \
  --alias local \
  --port 8080
```

项目也提供 `scripts/start_llama_server.sh` 作为本机开发辅助脚本。使用该脚本前，
需要在 `.env` 中补充 `LLAMA_SERVER_BIN`、`LLAMA_MODEL_PATH` 及所需的模型运行参数。
这不是运行 osCom Web UI 的必要条件。

可以在启动 osCom 前检查服务连接：

```bash
bash scripts/check_llama_server.sh
```

## 启动 osCom

在 llama-server 已就绪后启动 Web UI：

```bash
bash scripts/start_api.sh
```

默认访问地址为 <http://127.0.0.1:8000/>。

聊天页可查询知识库中的研究生院、财务处和实验室管理处政策。回答中的 Markdown
会在页面中渲染，检索和读取证据过程默认收起显示。

性能测试页只需选择一种提示词模式后运行测试：

| 页面选项 | 用途 |
| --- | --- |
| 常规提示词 | 公共上下文不保持稳定前置，用作基础对照。 |
| 前缀稳定提示词 | 让公共上下文和工具定义保持稳定前置。 |
| 前缀扰动提示词 | 在公共前缀中引入请求级扰动。 |

页面展示 Cache Hit、Host Cache 占用、TTFT P50/P95 与 E2E Avg/P50/P95。测试始终连接
当前本地 llama-server，osCom 不提供缓存后端选择开关。

## 测试

```bash
PYTHONPATH=src python -m unittest discover -s tests -v
```

## 目录说明

```text
src/oscom/                 Web API、DocQA Agent 和性能测试代码
data/doc_qa/knowledge.json 内置政策知识库
scripts/                   服务检查与本机启动辅助脚本
tests/                     单元、API 与集成测试
docs/architecture.md       架构说明
docs/benchmarking.md       性能测试协议与指标定义
```

## 进一步阅读

- [架构说明](docs/architecture.md)
- [性能测试协议](docs/benchmarking.md)