# 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-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# osCom

osCom 提供两条彼此独立的运行路径：

- Web UI 中的 `doc_qa` 是模型驱动的真实 RAG Agent。
- Benchmark 使用确定性 scripted fixture 或真实 RAG Agent，评估 llama-server 的 Prompt Cache、并发吞吐和端到端延迟。

osCom 不管理 KV Cache。Legacy/Radix Prompt Cache、Unified KV 和设备执行均由独立的 llama-server 提供。

## 当前能力

### 交互 Agent

当前只开放 `doc_qa`：

1. 模型根据问题生成检索词。
2. 模型调用 `search_knowledge` 检索结构化知识库。
3. 模型调用 `read_knowledge` 读取完整证据。
4. 最终政策结论使用稳定的 `[chunk_id]` 引用。

用户询问“能问什么、有哪些政策”时不会做相似度检索，而是通过 `list_knowledge_topics` 动态读取完整知识库目录。

交互请求会先进行事项和缺失条件分析；需要关键信息时先澄清。读取证据后会进行一次有界的回答复核，最终回答按结论、材料、步骤、时限、注意事项和依据组织。会话还会保存有界的事项、已知事实和已读取证据摘要。上述额外阶段只属于 Web 交互 Agent，不计入 `rag-agent-e2e` Benchmark 的固定工具循环。

知识库位于 `data/doc_qa/knowledge.json`，涵盖研究生请假、科研差旅报销和实验室门禁。无关问题返回 `no_results`，不会默认回退到请假制度。

Web UI 展示检索词、工具调用、证据和引用验证，不展示模型隐藏思维链。服务端保存会话历史，同一个 session 不能同时写入两轮请求。

### Benchmark Fixture

`trip`、`customer_support` 和 scripted `doc_qa` 只作为可复现 workload，不在聊天 Agent 列表中出现。

Benchmark 支持两种 profile：

| Profile | 用途 | 默认输出 |
| --- | --- | ---: |
| `scripted-cache` | 固定工具路径，隔离 Prompt Cache 核心路径 | 1 token |
| `rag-agent-e2e` | 真实 DocQA RAG Agent 端到端体验 | 256 tokens |

`concurrency` 控制实际同时在途请求数。Web Benchmark 固定按用户轮次交错编排，每个 workload window 使用独立会话；`rag-agent-e2e` 会压缩跨轮历史，避免 4 并发共享 Unified KV 时耗尽上下文容量。

## 安装

项目要求 Python 3.10 及以上。当前环境使用 base Conda：

```bash
conda activate base
cd /root/competition/os-com
python -m pip install -r requirements.txt
```

开发测试依赖：

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

## 配置

`.env` 和 `.local/` 都位于项目根目录。创建运行配置：

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

至少确认：

```bash
LLM_BASE_URL=http://127.0.0.1:8080/v1
LLM_MODEL=local
LLAMA_SERVER_BIN=/absolute/path/to/llama-server
LLAMA_MODEL_PATH=/absolute/path/to/model.gguf
LLAMA_CTX_SIZE=8192
LLAMA_PARALLEL=4
LLAMA_CACHE_RAM=8192
LLAMA_CACHE_RADIX_PROMPT=on
DOC_QA_KNOWLEDGE_PATH=data/doc_qa/knowledge.json
```

`.local/env.sh` 或 `.local/envs.sh` 可保存本机 CANN、驱动和动态库环境。脚本会在 `.env` 之前加载它们。

## 启动

本仓库不负责构建 llama-server。已有二进制和模型时可运行：

```bash
bash scripts/start_llama_server.sh
```

脚本默认显式设置 4 slots、`--kv-unified` 和 8 GiB Host Prompt Cache。当前通过
`scripts/start_llama_server.sh` 中的 `LLAMA_PROMPT_CACHE_ARGS` 手工启用或关闭 Radix；
`LLAMA_CACHE_RADIX_PROMPT` 需要与实际模式一致，用于日志命名：

```bash
# Radix
LLAMA_CACHE_RADIX_PROMPT=on bash scripts/start_llama_server.sh

# Legacy
LLAMA_CACHE_RADIX_PROMPT=off bash scripts/start_llama_server.sh
```

每次启动都会生成独立日志：

```text
tmp/llama-server/radix-20260723T120000Z.log
tmp/llama-server/legacy-20260723T121500Z.log
```

`tmp/llama-server/current.log` 始终指向最近一次启动的 server 日志。Web UI 不接收日志路径，
Benchmark 自动读取该入口。只有 CLI 需要分析其他历史日志时才使用 `--server-log` 覆盖。

检查 OpenAI-compatible API：

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

启动 osCom Web UI：

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

浏览器访问 `http://127.0.0.1:8000/`。Web UI 是唯一聊天界面；项目不再提供终端聊天入口。

## 运行 Benchmark

Web UI 的 Benchmark 标签页和 CLI 调用同一个 runner。

不连接模型的 scripted smoke test：

```bash
PYTHONPATH=src python -m oscom.benchmark \
  --agent doc_qa \
  --backend mock \
  --profile scripted-cache \
  --mode cache_friendly \
  --concurrency 4 \
  --interleave \
  --no-warmup \
  --json
```

连接 llama-server 的 4 并发 Prompt Cache 测试：

```bash
PYTHONPATH=src python -m oscom.benchmark \
  --agent doc_qa \
  --backend langgraph \
  --profile scripted-cache \
  --mode cache_friendly \
  --concurrency 4 \
  --output-tokens 1 \
  --prompt-cache-backend radix \
  --clean-start \
  --server-slots 4 \
  --ctx-size 8192 \
  --kv-unified \
  --cache-ram-mib 8192 \
  --interleave \
  --json
```

真实 RAG Agent profile：

```bash
PYTHONPATH=src python -m oscom.benchmark \
  --agent doc_qa \
  --backend langgraph \
  --profile rag-agent-e2e \
  --concurrency 4 \
  --output-tokens 256 \
  --prompt-cache-backend radix \
  --interleave \
  --json
```

Legacy 与 Radix 必须分别重启 server，并保持模型、量化、ctx-size、slots、Unified KV、Host Cache RAM、请求集合和输出 token 上限一致。

## 统计边界

- 主 Prefill、Decode 和 Cache Hit 来自 measurement pass 的全部模型调用。
- warmup 结果单独存储，不进入主平均值。
- server log 只解析 measurement 的起止 byte offset。
- HBM 只在 pass 边界采样，不进入 Agent E2E。
- Radix run delta 与整棵树的 cumulative state 分开记录。
- Web 主表展示请求 E2E Avg/P50/P95、Cache Hit、Throughput 和 Prefix Dedup。Prefill、Host Cache 与 HBM 仅保留在 JSON 明细中，不在主表展示。
- 批次 makespan 仅保留在 JSON 中，作为计算 requests/s 和 output tokens/s 的时间分母。
- 后端类型、clean/dirty、slots、ctx-size、Unified KV 和 cache RAM 由运行参数显式写入结果，不根据占用量猜测。

## 测试

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

测试覆盖 RAG 语义路由、无结果处理、引用验证、服务端会话、scripted 多轮、warmup 隔离、多模型调用 timing 聚合和 4 请求真实重叠。

## 目录

```text
src/oscom/
  agent.py                 交互 Agent 服务调度器
  api.py                   Web UI、HTTP/SSE 和 Benchmark API
  agents/doc_qa/           真实 RAG Agent 与 scripted fixture
  agents/trip/             Benchmark fixture
  agents/customer_support/ Benchmark fixture
  bench/scheduler.py       并发请求分组与调度描述
  benchmark.py             Benchmark runner、指标和 CLI
  core/session.py          服务端内存会话
  core/graph.py            模型驱动工具循环
  metrics.py               llama-server/Radix/HBM 指标解析

data/doc_qa/knowledge.json 结构化硬编码知识库
```