# rag_model_server

**Repository Path**: xhyym/rag_model_server

## Basic Information

- **Project Name**: rag_model_server
- **Description**: 提供给 rag 的模型服务，对外提供接口：向量化，重排，文本语义切分
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# rag_model_server

`rag_model_server` 是一个独立的模型推理服务，用来给 RAG 主服务提供三类基础能力：

- 文本嵌入 `embedding`
- 向量化 `vectorize`
- 文本重排 `rerank`

如果你们已经把 `Qwen3-8B` 从本项目拆出去，改成独立的 vLLM 服务，可以直接看这份教程。这份教程已经按你们现场验证成功的 `vLLM 0.9.2 + DTK 25.04.2 + 8004 端口 + 1 号卡` 方案整理：

- [K100_AI 上用 vLLM 部署 Qwen3-8B（8004 端口）](docs/K100_AI_VLLM_QWEN3_8B.md)
- [K100_AI 上部署 MinerU（Pipeline 模式，8003 端口）](docs/K100_AI_MINERU_PIPELINE.md)

这个项目默认按中文医疗 RAG 场景配置：

- Embedding 模型：`bge-m3`
- Rerank 模型：`bge-reranker-v2-m3`
- 默认只使用 `1` 号 GPU
- 运行时 Python 版本：`3.10`
- 依赖管理：`requirements.txt`
- 部署方式：zip 离线包 + Docker 挂载代码运行

## 目录结构

```text
rag_model_server/
├── app/
│   ├── config.py
│   ├── main.py
│   ├── model_manager.py
│   └── schemas.py
├── docker/
│   ├── Dockerfile.runtime
│   └── entrypoint.sh
├── scripts/
│   ├── download_offline_bundle.sh
│   ├── run_docker.sh
│   └── smoke_test.py
├── Dockerfile
├── README.md
└── requirements.txt
```

## 默认模型目录

服务默认从下面两个目录加载模型：

- `/app/models/rag/BAAI/bge-m3`
- `/app/models/rag/BAAI/bge-reranker-v2-m3`

如果你的目录名不同，可以在启动容器时通过环境变量覆盖：

- `EMBEDDING_MODEL_PATH`
- `RERANK_MODEL_PATH`

默认运行策略：

- 默认通过 `ROCR_VISIBLE_DEVICES=1` 和 `HIP_VISIBLE_DEVICES=1` 只暴露物理 `1` 号卡
- 由于可见设备会被重映射，应用内默认推理设备是 `cuda:0`，它实际对应物理 `1` 号卡

## API

### 1. 健康检查

```bash
curl http://127.0.0.1:8001/healthz
```

### 2. Embeddings

```bash
curl -X POST http://127.0.0.1:8001/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "input": ["发热三天伴咳嗽", "否认药物过敏史"],
    "normalize": true
  }'
```

### 3. Vectorize

`/v1/vectorize` 和 `/v1/embeddings` 使用同一套底层模型，但返回格式更偏工程化，便于你们主服务直接消费。

```bash
curl -X POST http://127.0.0.1:8001/v1/vectorize \
  -H "Content-Type: application/json" \
  -d '{
    "input": "社区获得性肺炎的经验性治疗",
    "normalize": true,
    "pooling": "cls"
  }'
```

### 4. Rerank

```bash
curl -X POST http://127.0.0.1:8001/v1/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "query": "患者有没有提到药物过敏",
    "documents": [
      "患者否认青霉素过敏史。",
      "主诉发热三天，伴咳嗽咳痰。",
      "既往高血压病史五年。"
    ],
    "top_n": 2,
    "normalize": true
  }'
```

## 离线打包

执行：

```bash
cd /Users/zuoban/works/rag_model_server
bash scripts/download_offline_bundle.sh
```

这个脚本是在“有网的打包机器”上执行的，不是目标测试机/内网机的启动脚本。

脚本会做三件事：

1. 下载 `requirements.txt` 对应的 wheels
2. 复制当前项目源码
3. 打包出一个可拷贝的 zip 离线包

当前脚本会直接使用机器当前 `pip` 的默认源配置，不再额外写死镜像源。

并且会主动清理这些不需要打进离线包的轮子：

- `torch`
- `torchvision`
- `torchaudio`
- `triton`
- `nvidia_*`

原因是海光基础镜像已经自带可用的 `torch` 环境，这个项目不应该再往目标机器里带一套通用 CUDA 版本依赖。

默认按海光服务器目标环境准备：

- 基础镜像：`image.sourcefind.cn:5000/dcu/admin/base/vllm:0.9.2-ubuntu22.04-dtk25.04.2-py3.10`
- Docker 平台：`linux/amd64`
- Python ABI：`cp310`
- manylinux 平台：`manylinux2014_x86_64`

默认输出目录：

- `/Users/zuoban/works/rag_model_server/offline_bundle`

执行完成后还会生成：

- `/Users/zuoban/works/rag_model_server/offline_bundle/rag_model_server_offline_bundle.zip`

## Docker 启动

目标机器上先解压 zip，然后进入项目目录执行：

```bash
cd /path/to/rag_model_server
bash scripts/run_docker.sh
```

默认行为：

- 使用 `offline_bundle/wheels` 离线构建运行时镜像
- 使用海光 DCU 推荐的容器参数
- 将宿主机项目目录挂载到容器里运行
- 将宿主机 `/app/models/rag` 挂载到容器内 `/app/models/rag`
- 监听 `8001` 端口
- 默认只使用物理 `1` 号 GPU

这种模式的好处是：

- 目标机器不需要联网下载 Python 依赖
- 代码是通过挂载目录运行的
- 你在宿主机改代码后，只需要 `docker restart rag-model-server`

如果你改了 `requirements.txt`，需要重新构建运行时镜像：

```bash
cd /path/to/rag_model_server
FORCE_REBUILD_IMAGE=1 bash scripts/run_docker.sh
```

注意：

- `run_docker.sh` 依赖目标机器本地已经有基础镜像 `BASE_IMAGE`
- 如果目标机器没有这个基础镜像，需要提前手动导入或准备好

## 一键冒烟测试

服务启动后，可以直接执行：

```bash
cd /path/to/rag_model_server
python3 scripts/smoke_test.py
```

当前脚本默认会请求：

- `http://172.16.240.120:8001`

默认会依次测试：

- `/`
- `/healthz`
- `/v1/embeddings`
- `/v1/vectorize`
- `/v1/rerank`

## 说明

- 这个服务不做鉴权，默认就是内部工具服务。
- 这个服务只负责 embedding / rerank 推理，不负责向量库存储和业务编排。
- 生成类能力已经建议迁移到独立 vLLM 服务。
- 如果后续你们想把 sparse embedding / ColBERT vector 也补进来，可以在这个项目上继续扩展。

## Qwen3-8B LoRA 一键流程（ms-swift）

如果你希望在 K100 上做“医疗查询改写 + 图谱抽取”方向的 LoRA 微调，并且要一键完成“训练 + 合并 + 启动”，可以直接用下面脚本：

```bash
cd /Users/zuoban/works/rag_model_server
bash scripts/train_merge_start_qwen3_8b_lora_k100.sh
```

这个脚本会自动执行：

1. 准备两任务训练集（默认 20000 条）  
   `datasets/qwen3_multitask_outpatient_20k.jsonl`
2. 在 Docker 内调用 `ms-swift` 做 LoRA SFT
3. 自动查找最新 adapter checkpoint 并 merge LoRA
4. 调用 `scripts/start_qwen3_8b_k100.sh` 用 merged 模型重启 vLLM

默认训练脚本会安装 `ms-swift==3.12.6`，这是为了兼容当前 K100 + vllm0.9.2 基础镜像里的 torch 版本，避免 `FSDPModule` 导入报错。  
脚本会按 `ms-swift` 版本自动选择 LoRA 参数名（3.x 用 `--train_type`，4.x 用 `--tuner_type`），并在参数不兼容时报错时自动回退。  
如果你确认镜像 torch 已升级且兼容，可通过环境变量覆盖：

```bash
MS_SWIFT_VERSION=4.1.1 bash scripts/train_merge_start_qwen3_8b_lora_k100.sh
```

新增文件：

- `scripts/train_merge_start_qwen3_8b_lora_k100.sh`（一键入口）
- `scripts/ms_swift_train_merge_inside_container.sh`（容器内训练与合并）
- `scripts/prepare_qwen3_8b_multitask_outpatient_dataset.py`（两任务训练集生成器）
- `datasets/qwen3_multitask_outpatient_20k.jsonl`（默认训练集）

## 门诊两任务数据集（20k）

默认生成“查询改写 + 图谱抽取”两任务门诊数据集。

图谱抽取样本会优先读取医生审核表作为监督源，默认自动搜索：

- `/Users/zuoban/works/hospital_rag/data/review/门诊常用病种医生审核表.xlsx`

这样模型学习的图谱字段会直接对齐审核表中的这些列：

- `病症名称`
- `病症别名`
- `医学体系`
- `疾病概述`
- `症状`
- `检查`
- `指标`
- `常用药物`
- `诱发因素`
- `相关病症`
- `管理要点`
- `补充说明`

```bash
cd /Users/zuoban/works/rag_model_server
python3 scripts/prepare_qwen3_8b_multitask_outpatient_dataset.py \
  --output datasets/qwen3_multitask_outpatient_20k.jsonl \
  --samples 20000 \
  --review-excel /Users/zuoban/works/hospital_rag/data/review/门诊常用病种医生审核表.xlsx \
  --rewrite-ratio 1 \
  --graph-ratio 1
```

默认比例：

- 查询改写 `10000`
- 图谱抽取 `10000`

直接用这份数据集执行一键训练：

```bash
cd /Users/zuoban/works/rag_model_server
DATASET_PATH=/Users/zuoban/works/rag_model_server/datasets/qwen3_multitask_outpatient_20k.jsonl \
REGENERATE_DATASET=0 \
bash scripts/train_merge_start_qwen3_8b_lora_k100.sh
```