# hospital_rag

**Repository Path**: elfbobo_admin_admin/hospital_rag

## Basic Information

- **Project Name**: hospital_rag
- **Description**: 医疗场景的 rag 知识库建立：基于 langchain+neo4j 建立全方位医疗知识库
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hospital_rag

## 文档导航

- 整体设计文档：[`docs/rag_overall_design.md`](/Users/zuoban/works/hospital_rag/docs/rag_overall_design.md)
- Neo4j 关系模型：[`docs/neo4j_schema.md`](/Users/zuoban/works/hospital_rag/docs/neo4j_schema.md)

## 1. 项目目标

在内网环境下建设医疗知识库 RAG 系统，支持：

- 对外主职责是提供统一 `search` 检索接口
- 返回检索命中的文件内容、分数与溯源元信息
- 多知识库检索（查询时可指定知识库）
- 可追溯引用（文档、页码、chunk）
- 向量检索 + 图谱检索 + 重排
- 入库、离线评测脚本、测试页等能力仅作为内部支撑，不是对外主合同

## 2. 已确定技术栈（当前版本）

- 编排框架：`LangChain`（流程复杂时可加 `LangGraph`）
- 向量库：`Milvus`
- 重排器：`BAAI/bge-reranker-v2-m3`
- 图数据库：`Neo4j`
- 业务数据库：`MySQL`（存文档解析结构、chunk 元信息、任务与审计记录）
- 对象存储：优先复用现有可用存储（Milvus 自带 MinIO 可用，但建议做 bucket/path 隔离）
- 观测：先不接 `Langfuse`，后续按需要接入本地 self-host 版本

## 3. 运行与部署约束

- 部署环境：完全内网
- 当前策略：不额外引入 Docker 新实例，直接复用现有中间件环境
- 设计原则：先打通主链路，再逐步补齐可观测、评估、自动化运维

## 4. 核心数据流（v1）

1. 文档接入（PDF/医疗文书等）
2. 文档解析与切分（按文档类型策略）
3. 写入 MySQL（解析结构 + 元信息）
4. 写入 Milvus（向量索引）
5. 抽取实体关系并写入 Neo4j（图谱）
6. 查询时执行：
   - 向量召回
   - 图谱召回
   - 重排（bge-reranker-v2-m3）
   - 返回检索结果与证据来源（不负责生成最终答案）

## 5. 文档切分与元信息要求（v1）

- 切分应按文档类型配置（如指南、病历、检验报告、药品说明）
- 每个 chunk 至少绑定：
  - `kb_id`
  - `doc_id`
  - `chunk_id`
  - `page_start/page_end`
  - `section_path`
  - `version`
  - `sensitivity_level`

## 6. 权限与审计（v1）

- 查询必须显式指定 `kb_ids`
- 服务端执行权限交集校验（用户可访问知识库 ∩ 请求知识库）
- 检索前置过滤租户/知识库/敏感级别
- 返回结果必须包含证据来源
- 记录 `trace_id` 贯穿全链路，便于后续接入 Langfuse

## 7. 近期实施顺序（建议）

1. 先落地文档解析 + 切分 + 元信息入库
2. 打通 Milvus 检索与 Neo4j 图谱检索
3. 接入 reranker 并完成 topK -> topN 重排链路
4. 统一 `search` API 响应格式（含 `content` / `score` / `citation`）
5. 再评估并接入本地 Langfuse（可选）

## 8. 当前目录用途

本目录用于后续 `hospital_rag` 业务代码与文档沉淀，建议结构如下（可按实际调整）：

```text
hospital_rag/
  README.md
  docs/
  app/
  scripts/
  tests/
```

## 9. 当前已落地的项目骨架

```text
hospital_rag/
  .env.dev
  .env.prod
  requirements.txt
  app/
    api/
    core/
    models/
    services/
    tasks/
    static/
    main.py
  docs/
    neo4j_schema.md
  scripts/
    init_mysql.sql
    run_docker.sh
```

## 10. 检索接口约束（当前定义）

- 这是当前对外主接口
- 接口：`POST /api/v1/retrieval/search`
- 请求参数：
  - `tenant_id` 必填
  - `department_id` 可选
  - `doctor_id` 可选
  - `title_id` 可选
  - `query` 查询文本
  - `score_threshold` 分值阈值
  - `top_k` 检索条数
  - `knowledge_base_ids` 知识库 ID 数组，可选；不传时按租户下知识库检索
- 返回结果必须带溯源字段：
  - `knowledge_base_id`
  - `knowledge_base_code`
  - `source_domain`
  - `doc_id/chunk_id` 或 `event_id/artifact_id`
  - `download_url`
- 上游如果只关心检索结果，重点读取：
  - `hits[*].content`
  - `hits[*].score`
  - `hits[*].citation`

说明：

- 当前仓库里仍保留了入库、`rag-test` 页面与离线评测脚本等内部支撑能力，但对外最核心的接口只有 `search`
- 如果后续要继续收敛系统边界，优先保留这一层即可

## 11. 入库接口约束（当前定义）

- 接口：`POST /api/v1/ingestion/documents`
- 支持上游传入文件地址 `file_url`
- 支持前端显式指定 `document_type` 与 `chunking_strategy`
- 如果 `chunking_strategy` 不传，服务端按“文档类型默认策略”处理（例如 `excel -> table`）
- 支持前端传入切分参数：`chunk_size/chunk_overlap/parent_chunk_size/child_chunk_size`
- 当前版本会完成：
  - `airag_knowledge / airag_knowledge_doc / rag_ingestion_jobs` 落库
  - 通过 Celery 投递后台任务处理
  - 处理链路包含：解析、切分、向量化、Milvus 索引写入、轻量图谱抽取与保存

### 11.1 解析器能力（当前）

- v1 仅支持非音视频文档；音频/视频请先完成转写后再按文本类文档接入
- 解析后端固定优先为：`LangChain`
- LangChain 失败时自动回退内置解析（无需额外配置）
- 解析阶段会尽量保留溯源字段，并在切片后继续透传到 `rag_document_chunks`
- 当前已接入：
  - `txt`：`TextLoader`
  - `markdown`：`TextLoader` + 标题层级切段，生成 `section_path`
  - `html`：`BSHTMLLoader`，失败时回退内置 HTML 文本提取
  - `excel(csv/tsv/xlsx/xls)`：统一按“行标题 + 行内容”解析，输出格式为 `sheet=...; row=...; 列名: 值 | ...`，并保留 `table_index/table_row_start/table_row_end`
  - `pdf`：`PyPDFLoader`，按页保留 `page_start/page_end`
  - `word(docx)`：`Docx2txtLoader`，失败时回退 `python-docx`
  - `word(doc)`：优先 `LangChain + Unstructured`；失败时尝试通过 `soffice` 转成 `docx` 后解析
  - `ppt/pptx`：优先 `LangChain + UnstructuredPowerPointLoader`；失败时回退 `python-pptx`，并按 `slide` 保留 `section_path`

## 11.2 前端对接状态说明（重要）

前端上传并提交入库后，文档状态建议从 `airag_knowledge_doc` 读取，主要字段：

- `status`：文档整体处理状态
- `parse_status`：解析/切分状态
- `parse_error_message`：失败原因（失败时有值）
- `requested_chunking_strategy`：前端提交的切分方式
- `resolved_chunking_strategy`：服务端最终采用的切分方式

状态流转：

- `draft`：已受理，待后台任务执行
- `building`：后台任务处理中
- `complete`：处理完成（已切分并写入索引）
- `failed`：处理失败（查看 `parse_error_message`）

说明：

- 服务内部也兼容旧值 `pending/running/succeeded`
- 但文档表当前落库的主状态值以 `draft/building/complete/failed` 为准

## 12. 本地启动

1. 创建虚拟环境：`python3.11 -m venv .venv`
2. 激活环境：`source .venv/bin/activate`
3. 安装依赖：`pip install -r requirements.txt`
4. 复制环境文件：`cp .env.dev .env`
5. 按需初始化 MySQL 表结构：执行 [`scripts/init_mysql.sql`](/Users/zuoban/works/hospital_rag/scripts/init_mysql.sql)
6. 启动服务：`uvicorn app.main:app --reload --host 0.0.0.0 --port 8000`
7. 如果未开启 `start_celery_with_main`，需单独启动 Celery worker

如果使用 `scripts/run_docker.sh` 启动容器，当前推荐显式指定运行环境文件：

- dev：`bash scripts/run_docker.sh dev`
- prod：`bash scripts/run_docker.sh prod`

说明：

- 对 API 服务来说，脚本默认按 CPU 模式启动，不需要传显卡参数。
- 脚本会自动把 `dev -> .env.dev`、`prod -> .env.prod` 映射成 `docker run --env-file`。
- 如果后续确实需要在容器里启用 DCU，再显式传：
  `ENABLE_DCU_RUNTIME=1 bash scripts/run_docker.sh dev 1`

## 13. 当前 dev 环境（已配置）

- MySQL：`172.16.240.120:3306/agent_applications`
- Redis：`172.16.240.120:6379`
- Milvus：`172.16.240.120:19530`
- Neo4j：`bolt://172.16.240.120:7687`
- 模型服务：`http://172.16.240.120:8001`
- 后台任务：默认可由 `main.py` 拉起 Celery worker，也可独立启动
- Milvus 集合：`rag_chunk_vectors`
- MySQL 表命名统一使用 `rag_` 前缀

## 14. 当前已接入的核心能力

- HTTP 调用统一使用 `httpx.AsyncClient` 连接池复用
- 已接入模型服务：
  - `/v1/embeddings`
  - `/v1/rerank`
  - 独立 LLM 服务 `/v1/chat/completions`（查询改写、图谱抽取等生成型任务）
- 已实现 MySQL / Redis / Milvus / Neo4j 的基础连接与初始化
- 已实现检索主链路：
  - query rewrite（调用独立 LLM 服务）
  - 原始 query + 改写 query 的多路向量召回
  - query embedding
  - Milvus 向量检索
  - MySQL 溯源补全
  - Neo4j 图谱补充
  - rerank 精排
  - 对外返回 `hits + citation + graph_tree`
- 已实现入库增强链路：
  - 文档重跑时自动清理旧 chunk / 旧向量 / 旧图关系
  - 上传后对 chunk 做轻量实体关系抽取
  - 抽取结果写入 `rag_graph_entities / rag_graph_relations`
  - 同步简化图到 Neo4j，供 `graph_paths` 补充返回
## 15. 当前建模范围

- 通用知识库：`knowledge_bases/documents/document_chunks`
- 导诊与病历知识库：`patient_encounters/episode_events/artifacts/medical_facts`
- 图谱：`graph_entities/graph_relations`
- 检索审计：`retrieval_logs`

这版先把接口、数据模型、Neo4j 关系类型和 RAG 检索骨架落下来，后面你新增表时可以继续往上叠加。