# quality-agent

**Repository Path**: WxBiologics/quality-agent

## Basic Information

- **Project Name**: quality-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Quality Agent — 文档质量审查系统

面向生物制药行业的文档质量审查后端系统。将客户的法规、SOP、工艺文件解析成可检索索引，利用 LLM + 确定性工具完成一致性审查，产出带证据锚点、可逐级追溯的审查报告。

## 环境要求

| 项 | 要求 |
|---|---|
| Python | **3.12+**（3.14 不支持 PaddlePaddle，不兼容） |
| 操作系统 | Windows 10/11（开发）、Rocky Linux 9（生产部署） |
| 磁盘 | ≥ 2GB（venv + 模型 + 数据） |
| 内存 | ≥ 8GB（OCR 进程池 + LLM 并发） |

## 技术栈

| 项 | 选型 |
|---|---|
| 语言 | Python 3.12 |
| Web 框架 | FastAPI + Uvicorn |
| 数据库 | SQLite（状态、缓存、追溯全落库） |
| LLM 调用 | 统一网关（限流/记账/缓存），支持 A/B 双模型 |
| OCR | RapidOCR（默认）/ PaddleOCR（Linux 部署） |
| 文档解析 | PDF（含扫描件 OCR）/ Word / Markdown |
| 部署 | Rocky Linux 9 内网离线单机部署 |
| 进度推送 | SSE（Server-Sent Events） |

## 整体架构

```
┌─────────────────────────────────────────────────────┐
│               HTTP 平台壳（FastAPI）                  │
│  任务提交 / SSE 进度推送 / 制品下载 / Arena 评审       │
├─────────────────────────────────────────────────────┤
│               技能层（Skill / 声明式管线）              │
│  regulatory_audit · process_parameter_consistency    │
├─────────────────────────────────────────────────────┤
│               工具层（Tool / 原子操作）                 │
│  法规审计线 4 个工具 + 工艺参数线 5 个工具              │
├─────────────────────────────────────────────────────┤
│            解析与索引层（Indexer）                      │
│  pdf_doc_parser · l1_l2_index_builder               │
└─────────────────────────────────────────────────────┘
```

## 快速开始

### 1. 安装依赖

```powershell
cd d:\yaoming\quality-agent-test\wuxibiologics_backend

# 建虚拟环境（Python 3.12+）
python -m venv venv
venv\Scripts\Activate

# 安装运行时依赖（Windows 需先设 UTF-8 编码，避免中文注释报错）
$env:PYTHONUTF8="1"
pip install -r requirements-runtime.txt

# 可选：安装 OCR 后端（解析扫描件需要）
# RapidOCR（推荐，Windows/Linux 通用，无兼容性问题）
pip install rapidocr-onnxruntime

# PaddleOCR（仅 Linux 部署，Windows 有 PIR/OneDNN 兼容性问题）
# pip install paddlepaddle==3.3.1 paddleocr==3.7.0
```

### 2. 准备数据目录

```powershell
# 数据根目录（QA_HOME），其下自动创建子目录
$env:QA_HOME = "d:\yaoming\quality-agent-test\wuxibiologics_backend\data"
# 首次启动会自动创建：raw/ index/ artifacts/ db/ logs/
```

### 3. 启动服务

```powershell
cd d:\yaoming\quality-agent-test\wuxibiologics_backend\app

# 必需环境变量
$env:QA_HOME = "d:\yaoming\quality-agent-test\wuxibiologics_backend\data"

# LLM 网关配置（没有真实网关可先填占位值，LLM 相关功能会报错但不影响服务启动）
$env:QA_LLM_BASE_URL = "http://your-gateway/v1"
$env:QA_LLM_API_KEY = "your-api-key"

# 启动
cd C:\Users\li.yadong002.ext\Desktop\quality-agent\quality-agent

$env:PYTHONUTF8 = "1"
.\venv\Scripts\python.exe -m pip install -r requirements-runtime.txt

..\venv\Scripts\python.exe -m uvicorn quality_agent.enterprise.api.app:create_app --factory --host 0.0.0.0 --port 8000

```

### 4. 验证

浏览器打开 `http://localhost:8000/docs`，能看到 FastAPI 交互式文档即服务启动成功。

先调 `GET /components` 查看已注册的组件。

## 文档解析与索引（CLI）

文档解析与索引是独立于 API 服务的 CLI 操作，是后续审计任务的**前置步骤**。

### 准备源文档

将 `.pdf` / `.docx` 文件按**文档族**（子目录）组织：

```
<你的文档目录>/
├── LAW/                    ← 法规文档族
│   ├── 21_CFR_Part_211.pdf
│   └── 药品生产质量管理规范.pdf
├── SOP/                    ← 标准操作规程族
│   └── MFG3洁净区更衣程序.pdf
└── QRA/                    ← 质量风险评估族
    └── WX-QRA-00648.pdf
```

- 一级子目录名 = 文档族名（LAW/SOP/QRA 等）
- 直接放在根目录的文件归入 `all` 族
- 只识别 `.pdf` 和 `.docx`，其他格式自动跳过

### 运行索引命令

**Windows PowerShell：**

```powershell
cd d:\yaoming\quality-agent-test\wuxibiologics_backend

# 设置环境变量
$env:PYTHONUTF8="1"
$env:PYTHONPATH="app"

# 执行索引（替换为你的实际路径）
# --ocr-backend rapidocr  使用 RapidOCR（推荐）
# --ocr-backend paddle    使用 PaddleOCR（仅 Linux）
# --ocr-backend none      关闭 OCR（纯文字型 PDF 足够）
# --ocr-page-workers 0    自动 CPU 并行度

venv\Scripts\python.exe -m quality_agent.enterprise.indexing.cli "d:\yaoming\quality-agent-test\data" --ocr-backend rapidocr --ocr-page-workers 0 --home "d:\yaoming\quality-agent-test\wuxibiologics_backend\data"
```

**Linux / Git Bash：**

```bash
cd /d/yaoming/quality-agent-test/wuxibiologics_backend

PYTHONPATH=app venv/bin/python -m quality_agent.enterprise.indexing.cli \
    "/d/yaoming/quality-agent-test/data" \
    --ocr-backend rapidocr \
    --ocr-page-workers 0 \
    --home "/d/yaoming\quality-agent-test/wuxibiologics_backend\data"
```

### 可选参数

| 参数 | 说明 | 默认值 |
|---|---|---|
| `--home <路径>` | 数据根目录（也可用环境变量 `QA_HOME`） | 必填 |
| `--ocr-backend none/rapidocr/paddle/auto` | OCR 后端 | `none`（关闭） |
| `--ocr-page-workers <N>` | 页级 OCR 并行度（0=自动） | 自动 |
| `--no-ml` | 关闭 TF-IDF ML 打标 | 默认开启 |
| `--debug-content` | 索引保留正文（调试用） | 默认不保留 |
| `--force` | 忽略指纹强制重建索引 | 默认幂等跳过 |
| `--import-parsed` | 导入已解析产物（跳过重新解析） | — |
| `--raw-dir <路径>` | 原文目录（仅 `--import-parsed` 时配对用） | — |

### OCR 后端选择

| 后端 | 适用环境 | 说明 |
|---|---|---|
| `none` | 纯文字型 PDF | 不启用 OCR，pdfplumber 直接提取文本/表格 |
| `rapidocr` | Windows + Linux | **推荐**。ONNX Runtime 推理，同 PP-OCR 模型权重，无兼容性问题 |
| `paddle` | 仅 Linux | PaddlePaddle 框架，Windows 有 PIR/OneDNN 兼容性 bug |
| `auto` | 自动探测 | 优先级：rapidocr > paddle > none |

### 输出目录结构

执行后 `--home` 指定的数据根目录下生成：

```
data/                           ← QA_HOME
├── raw/                        ← 原始文档存档（系统自动复制，只读，哈希命名）
├── index/
│   ├── parsed/                 ← 解析产物（结构化 JSON + Markdown）
│   │   ├── LAW/
│   │   ├── SOP/
│   │   └── QRA/
│   └── l1_l2/                  ← L1/L2 索引（每族 + combined 合并索引）
│       ├── LAW/
│       ├── SOP/
│       ├── QRA/
│       └── combined/
├── artifacts/                  ← 运行制品区（不可变）
├── db/                         ← SQLite 元数据 + 缓存
└── logs/                       ← 运行日志
```

每个索引目录包含 **14 个文件**（manifest、summary、L1 证据/事实/术语/节点、L2 词汇/打标/关系/标签、检索载荷、术语治理）。

### 幂等与增量

- **解析幂等**：同内容文档（SHA256 相同）不重复解析，自动跳过（标记 `cached`）
- **索引幂等**：输入文件指纹不变时不重建索引（标记「指纹一致跳过」）
- 新增/修改文档后重跑同一命令即可增量更新，已有内容不会重复处理；如需强制重建加 `--force`

## 核心功能

### 1. 法规一致性审计（regulatory_audit）

审计一条法规义务在已索引受控文件（SOP 等）中的覆盖一致性。

流程：`法规条款 → 原子义务抽取(LLM) → 证据检索(确定性) → 六态判定+双模型复核(LLM) → 审计报告生成`

### 2. 工艺参数一致性（process_parameter_consistency）

核对一组工艺文档（PC 报告/PI/PPQ 方案/PPQ 报告）之间的参数一致性。

流程：`工艺文档 → 参数抽取 → 跨文档对齐 → 参数比对 → 一致性报告`

### 3. 批量任务

一次提交多条法规条款，服务端逐条执行审计，产出批次级汇总文件。

### 4. Arena 对比评测

同一输入跑多个 skill 版本，用于对比评测与人工评审。

## API 接口

| 接口 | 功能 |
|---|---|
| `GET /components` | 列出所有注册的组件 |
| `POST /jobs` | 提交审查任务（异步，返回 202） |
| `GET /jobs/{job_id}` | 查询任务状态 |
| `GET /runs/{run_id}` | 获取运行状态快照 |
| `GET /runs/{run_id}/events` | SSE 实时进度流 |
| `GET /runs/{run_id}/artifacts` | 获取制品清单 |
| `GET /artifacts/{id}` | 下载制品文件 |
| `POST /batches` | 批量提交法规条款审计 |
| `POST /arena/runs` | 多 skill 同场对比评测 |
| `POST .../human-conclusion` | 人工节点结论提交 |

启动后访问 `http://<IP>:8000/docs` 查看完整交互式接口文档。

### 测试脚本

`scripts/` 目录提供接口测试脚本（纯 stdlib，无额外依赖）：

| 脚本 | 测试目标 |
|---|---|
| `scripts/test_jobs_api.py` | 法规审计（单条条款） |
| `scripts/test_batches_api.py` | 法规审计（批量条款） |
| `scripts/test_ppc_api.py` | 工艺参数一致性 |

```powershell
# 示例：测试工艺参数一致性
python scripts/test_ppc_api.py --base-url http://localhost:8000 --project CPP_UP
```

## 正式部署（Linux 目标机）

项目为 Rocky Linux 9 内网离线环境设计。

```bash
# 1. 安装（建 venv + 离线装依赖 + 建目录骨架）
bash install.sh

# 2. 自检（全绿才继续）
bash check_env.sh

# 3. 启动（交互式输入 LLM 网关地址和 key）
bash run.sh
```

可选安装 OCR 后端（需要解析扫描件时）：

```bash
# PaddleOCR（Linux 推荐）
/opt/quality-agent/app/venv/bin/pip install --no-index --find-links=wheels/paddle paddlepaddle paddleocr

# RapidOCR（备选）
/opt/quality-agent/app/venv/bin/pip install --no-index --find-links=wheels/rapid rapidocr-onnxruntime
```

## 环境变量配置

| 变量 | 必须 | 默认值 | 说明 |
|---|---|---|---|
| `QA_HOME` | 否 | `<项目目录>/data` | 数据根目录，其下自动分 `raw/index/artifacts/db/logs` |
| `QA_LLM_BASE_URL` | 否 | 内置缺省端点 | LLM 网关地址 |
| `QA_LLM_API_KEY` | 否 | 内置缺省值 | 网关 key（只进内存，不落盘） |
| `QA_PORT` | 否 | `8000` | 服务端口 |
| `QA_LLM_MAX_CONCURRENT` | 否 | `50` | 同时 LLM 请求上限 |
| `QA_LLM_RPM_LIMIT` | 否 | `200` | 每分钟请求上限 |
| `QA_LLM_TIMEOUT` | 否 | `120` | 单次调用读超时（秒） |
| `QA_LLM_MAX_RETRIES` | 否 | `4` | 限流/错误重试上限 |
| `QA_CPU_RESERVE` | 否 | `2` | 解析进程池预留 CPU 核数 |
| `QA_LOAD_THRESHOLD` | 否 | `1.0` | 系统负载阈值，超过则解析并发自动减半 |

## 目录结构

```
wuxibiologics_backend/
├── app/quality_agent/enterprise/
│   ├── api/                  # FastAPI 接口层
│   │   ├── app.py            # 应用入口（create_app 工厂）
│   │   ├── errors.py         # 统一错误处理
│   │   ├── schemas.py        # 请求/响应模型
│   │   └── sse.py            # SSE 实时进度流
│   ├── arena/                # Arena 多 skill 对比评测
│   ├── batch/                # 批次任务执行
│   ├── cache/                # SQLite 缓存
│   ├── components/           # 可插拔组件（自动扫描注册）
│   │   ├── indexers/         # 索引器
│   │   │   ├── pdf_doc_parser/        # 文档解析（PDF/Word/OCR）
│   │   │   └── l1_l2_index_builder/   # L1/L2 索引构建
│   │   ├── tools/            # 工具（原子操作）
│   │   │   ├── requirement_atom_extractor/  # 原子义务抽取
│   │   │   ├── evidence_retriever/          # 证据检索
│   │   │   ├── audit_assessor/              # 六态判定+双模型复核
│   │   │   ├── audit_report_builder/        # 审计报告生成
│   │   │   ├── fail_trace_builder/          # 失败追溯链
│   │   │   ├── parameter_extractor/         # 工艺参数抽取
│   │   │   ├── parameter_aligner/           # 跨文档参数对齐
│   │   │   ├── parameter_comparator/        # 参数比对
│   │   │   └── parameter_report_builder/    # 参数报告生成
│   │   └── skills/           # 技能（声明式 DAG 管线）
│   │       ├── regulatory_audit/            # 法规一致性审计
│   │       └── process_parameter_consistency/ # 工艺参数一致性
│   ├── config.py             # 路径与环境变量配置
│   ├── concurrency/          # CPU 并发控制
│   ├── contracts/            # 契约（枚举、ID 规范）
│   ├── db/                   # SQLite 数据层
│   ├── errors/               # 错误码与日志
│   ├── indexing/             # 索引 CLI
│   ├── llm/                  # LLM 统一网关
│   ├── pipeline/             # DAG 管线执行器
│   ├── registry/             # 组件注册表
│   ├── store/                # 制品与文档存储
│   └── trace/                # 追溯链
├── scripts/                  # 测试脚本
├── install.sh                # 安装脚本（Linux）
├── run.sh                    # 启动脚本（Linux）
├── check_env.sh              # 环境自检脚本
├── requirements-runtime.txt  # Python 依赖清单
├── DEPLOY_MANUAL.md          # 部署手册
├── API_REFERENCE.md          # 接口文档
└── CUSTOMIZE.md              # 自定义开发指南
```

## 设计亮点

1. **组件化 + 版本化**：所有 skill/tool/indexer 都是独立文件夹，按语义化版本管理，多版本并存互不影响，支持 Arena 对比评测
2. **全链路追溯**：每次工具调用、推理记录、审查结论都落库，从文档到结论形成完整证据链
3. **确定性 + LLM 混合**：关键判定环节（证据检索、比对）是确定性的，模型意见不覆盖确定性结论，保证可靠性
4. **离线内网部署**：全部单机运行，LLM 网关统一管控，API Key 只进内存不落盘
5. **渐进可见**：制品不必等任务跑完，每个 stage 完成后立即可下载
6. **SSE 实时进度**：前端可实时跟踪每个 stage 的状态变化，断线重连自动补发快照

## 相关文档

- [部署手册](DEPLOY_MANUAL.md) — Linux 目标机详细部署步骤
- [接口文档](API_REFERENCE.md) — 前端对接用 RESTful API 手册
- [自定义开发指南](CUSTOMIZE.md) — 如何扩展 skill/tool/indexer