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 加载的模型文件

安装

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

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

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

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

配置

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

cp .env.example .env

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

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 一致。例如：

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 scripts/check_llama_server.sh

启动 osCom

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

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 不提供缓存后端选择开关。

测试

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

目录说明

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

进一步阅读

• 架构说明
• 性能测试协议