Siemens RAGAS 项目总览

Siemens Healthineers · RAG Evaluation Platform

Siemens RAGAS RAG 评估平台：面向 CT 知识库的自动化质量评估闭环

本项目将 PDF 文档解析、题库生成、在线/离线 RAGAS 评测、报告沉淀与 Web 可视化 统一进一个可复用平台。CLI 与 FastAPI Web 控制台共享同一套 rag_eval 核心引擎，适合批量评估、持续优化与 Dify 实时评分集成。

3入口形态
CLI / Web / REST API

7RAGAS 指标
含 GT 依赖与非依赖

4核心流程
Build / Eval / Pipeline / Score

2适配模式
HTTP / Python Adapter

核心价值：将 PDF 资料转成可评测题库，再以 Siemens 医疗影像场景为中心完成答题、打分、加权汇总与报告产物沉淀，形成完整质量治理闭环。

1. 项目概述

项目名称：Siemens RAGAS RAG 评估平台。
目标：为西门子医疗影像 CT 知识库 RAG 系统提供自动化质量评估。
定位：既能作为离线评测框架，也能作为在线评估控制台与 API 服务，为知识库 QA、Prompt 迭代、检索策略优化提供统一基线。

业务闭环

PDF解析 → 题库生成 → RAGAS评测 → 报告可视化 → 再迭代。项目不仅覆盖评测本身，还覆盖评测数据源建设与运行产物管理。

运行方式

main.py 负责 CLI 评估与 dataset build，webmain.py 负责启动 FastAPI 控制台，webapp.server 暴露 REST API 与静态前端。

技术亮点

统一 CLI / Web / API 三入口阿里云 DocMind 文档解析 OpenAI 兼容模型接入 RAGAS 0.4.3 指标流水线在线 / 离线双模式评估 Python / HTTP Adapter 扩展机制场景 YAML 驱动 Pipeline 后台线程编排 Dify 实时单题评分接口 metric_weights + doc_weights 加权汇总历史 run 资产沉淀 Web 报告聚合与分布分析

2. 系统架构

平台采用“多入口 + 单评估核心”的结构。CLI 和 Web 控制台都汇入 rag_eval 核心引擎；API 层只负责任务编排、配置管理与结果查询。

┌─────────────────────────────────────────────────────────┐
│                    siemens_ragas 平台                    │
├─────────────┬───────────────────┬───────────────────────┤
│  CLI 入口   │   Web 控制台      │   REST API            │
│  main.py    │   webmain.py      │   FastAPI             │
├─────────────┴───────────────────┴───────────────────────┤
│                    核心评估引擎 (rag_eval)                │
├──────────────┬──────────────────┬────────────────────────┤
│ dataset_     │   execution/     │   metrics/             │
│ builder/     │   evaluator.py   │   pipeline.py          │
│ (PDF→题库)   │   (评估流程)     │   (RAGAS指标)          │
├──────────────┴──────────────────┴────────────────────────┤
│              外部依赖                                     │
│  阿里云DocMind (PDF解析) │ OpenAI兼容API (LLM/Embedding) │
└─────────────────────────────────────────────────────────┘

CLI 编排

main.py 通过互斥参数在 --scenario 与 --dataset-build-config 之间分派，分别进入评估流程与题库构建流程。

Web 服务

webmain.py 负责 uvicorn 启动、日志文件轮转与 host/port 配置；webapp.server 注册 runs、scenarios、evaluations、pipeline、score 等 API。

核心执行器

rag_eval.execution.runner 负责加载 scenario、构建模型与 adapter、调用 Evaluator 执行并写出标准化产物。

3. 核心模块说明

以下模块覆盖数据准备、评估执行、Web 管理与 Siemens 业务适配的主要职责边界。

模块	路径	职责
dataset_builder	`rag_eval/dataset_builder/`	PDF解析、source chunk 归一化、LLM 题目生成、草稿题库与构建产物写出。
execution	`rag_eval/execution/`	评估编排、在线/离线模式切换、adapter 调用、RAGAS 打分与结果聚合。
metrics	`rag_eval/metrics/`	RAGAS 指标注册、模型构建、评估管道装配、指标权重与文档权重聚合。
reporting	`rag_eval/reporting/`	运行产物写入、summary 生成、metadata 与 scenario 快照沉淀。
adapters	`rag_eval/adapters/`	HTTP/Python 应用适配器封装，把外部应用结果统一为 `answer / contexts / raw_response`。
webapp	`webapp/`	FastAPI Web 控制台、OpenAPI 文档、任务后台管理、场景扫描、历史报告查询。
apps	`apps/siemens_pdf_qa/`	西门子 CT 知识库问答适配器，基于 source chunk 证据构造 Prompt 并调用 OpenAI 兼容模型生成答案。

settings.py

集中读取 .env：OpenAI Key/Base URL、RAGAS Judge/Embedding 模型、并发、阿里云 DocMind、SCORE_API_TOKEN 等。

registry.py

定义 7 个受支持指标：faithfulness、answer_relevancy、context_recall、context_precision、noise_sensitivity、factual_correctness、semantic_similarity。

inline_scorer.py

为 /api/score 提供模块级缓存评分器，按 (judge_model, embedding_model) 复用 LLM 与 embedding 连接。

4. 数据流说明

项目围绕四条关键流程展开：题库构建、在线评估、API 全链路 Pipeline 与 Dify 实时评分。

Flow A: 题库生成流程（Dataset Build）

PDF文件 → 阿里云DocMind解析 → 文档切片(source_chunks)
→ LLM生成题目 → CSV题库文件 → 人工审核

对应入口：main.py --dataset-build-config；核心实现：rag_eval.dataset_builder.runner。

Flow B: RAGAS评估流程（Online Evaluation）

CSV题库 → 规范化样本 → 应用适配器(siemens_pdf_qa)
→ LLM答题 → RAGAS指标计算 → 加权得分 → 报告产物

对应 Siemens 场景：scenarios/online/siemens-pdf-question-bank-online.yaml，由 apps.siemens_pdf_qa.adapter:run 提供答案与证据片段。

Flow C: 全链路 Pipeline（API触发）

POST /api/pipeline/jobs → 后台线程 → Flow A → Flow B → 产物路径

由 webapp.services.pipeline_task_manager 在线程池中串行执行 parsing_documents → generating_questions → evaluating 三阶段，并返回 scores.csv / summary.md / dataset.csv 等路径。

Flow D: Dify实时评分（/api/score）

Dify Agent → POST /api/score → InlineScorer → RAGAS metrics → 得分JSON

当 ground_truth 缺失时，会自动跳过依赖参考答案的指标，并在响应中给出 skipped_metrics。

5. RAGAS 评估指标

平台当前支持 7 个指标，既覆盖回答忠实度和相关性，也覆盖对参考答案、噪声片段和语义相似度的衡量。

faithfulness

无需 ground_truth

回答对检索内容的忠实度，用于防止模型脱离证据“幻觉式”作答。

answer_relevancy

无需 ground_truth

衡量回答与问题本身的相关性，判断是否真正命中用户所问。

context_precision

无需 ground_truth

衡量检索片段的精准度，关注上下文中与回答真正相关的比例。

context_recall

需要 ground_truth

检索内容对标准答案覆盖程度，反映召回是否足够支撑正确作答。

noise_sensitivity

需要 ground_truth

系统对噪声检索片段的鲁棒性，越不受无关片段干扰越好。

factual_correctness

需要 ground_truth

与标准答案对齐的事实准确性，代码中作为端到端事实正确度指标。

semantic_similarity

需要 ground_truth

回答与标准答案的语义相似度，依赖 embedding，不需要额外 LLM 调用。

指标默认集合

在线评分默认

/api/score 的默认指标集合为 faithfulness、answer_relevancy、context_recall、context_precision。

6. API 接口文档

Web 层基于 FastAPI 提供任务提交、历史查询、LLM 配置管理与 Dify 实时评分接口。

方法	路径	说明
POST	`/api/pipeline/jobs`	提交全链路评估任务，后台线程自动执行 PDF 解析、题库生成和在线评估。
GET	`/api/pipeline/jobs/{id}`	查询指定 Pipeline 任务状态、阶段、日志和产物路径。
POST	`/api/score`	Dify 实时评分接口，接收单条问答并返回各指标得分与综合得分。
POST	`/api/llm-profiles/probe`	临时测试 LLM / Embedding 连通性，无需先保存配置。
POST	`/api/llm-profiles`	创建命名的 LLM 配置档案，可供场景或控制台复用。
POST	`/api/evaluations`	基于已有场景 YAML 启动一次后台评估任务。
GET	`/api/runs`	获取历史运行列表，用于控制台报告页与明细页渲染。

/api/score 请求示例

POST /api/score
Authorization: Bearer <token>
Content-Type: application/json

{
  "question": "双源CT的时间分辨率是多少?",
  "answer": "双源CT的单扇区时间分辨率为75ms。",
  "contexts": "双源CT采用两套管-探测器系统 |||| 单扇区采集旋转135度",
  "ground_truth": "双源CT单扇区时间分辨率为75ms，需旋转135度。",
  "context_separator": " |||| ",
  "metrics": [
    "faithfulness",
    "answer_relevancy",
    "context_recall",
    "context_precision"
  ],
  "judge_model": "gpt-5",
  "embedding_model": "text-embedding-3-small"
}

/api/score 响应示例

{
  "scores": {
    "faithfulness": 0.875,
    "answer_relevancy": 0.92,
    "context_recall": 0.81,
    "context_precision": 0.85
  },
  "weighted_score": 0.8638,
  "latency_ms": 3420,
  "skipped_metrics": [],
  "error": null
}

Pipeline API

返回 job_id 后即可轮询。阶段枚举包括 queued、running、parsing_documents、evaluating 与 done。

LLM Profiles

支持保存 base URL、API Key、model、timeout，并通过 /apply 将配置写回场景 YAML，同时可补充 metric/doc 权重。

Runs API

历史 run 会读取 summary.md、scores.csv 与 scenario.snapshot.yaml，聚合指标均值、分布和最低分样本。

7. 指标权重配置

平台支持两级权重：metric_weights 控制不同指标的重要性，doc_weights 控制不同文档对总体分数的影响。

metric_weights:
  faithfulness: 0.35
  context_recall: 0.25
  context_precision: 0.20
  answer_relevancy: 0.20

doc_weights:
  "322_双源CT.pdf": 2.0

weighted_score 计算逻辑：
1. 单样本综合分 = Σ(有效指标分 × 指标权重) / Σ(有效指标权重)
2. 总体综合分 = Σ(单样本综合分 × 文档权重) / Σ(文档权重)
3. 当权重未配置时，代码会自动退化为默认 1.0，即普通平均。
4. doc_weights 不仅影响总体综合分，也会影响控制台中按文档聚合后的指标均值。

代码依据

rag_eval.metrics.weights.compute_weighted_score() 负责单样本指标加权；compute_overall_weighted_score_mean() 负责跨样本文档加权。

配置入口

场景 YAML 可直接定义；Web 控制台也可通过 /api/llm-profiles/apply 将权重补丁写回场景文件。

8. 部署说明

仓库自带 deploy.sh，适合 Linux 一键部署 Web 控制台与相关依赖。

Linux 部署步骤

准备 Python 3.12+ 环境，执行 bash deploy.sh。
脚本会自动创建 .venv、安装 pyproject.toml 依赖，并补装 fastapi / uvicorn / httpx。
若 .env 不存在，将从 .env.example 复制一份模板。
脚本初始化 configs / logs / outputs / datasets 目录，并尝试生成 demo 数据。
最后使用 webmain.py 后台启动服务，默认端口 8800，冲突时回退到 8801。

常用命令

# 依赖安装
uv sync

# CLI 运行在线/离线评估
.\.venv\Scripts\python.exe main.py --scenario scenarios\online\siemens-pdf-question-bank-online.yaml

# CLI 运行题库生成
.\.venv\Scripts\python.exe main.py --dataset-build-config scenarios\siemens_build\siemens-pdf-build.yaml

# 启动 Web 控制台
.\.venv\Scripts\python.exe webmain.py --host 127.0.0.1 --port 8800

关键 .env 配置

变量	用途	示例 / 默认
`OPENAI_API_KEY`	OpenAI 兼容接口凭据	`your-api-key`
`OPENAI_BASE_URL`	统一 LLM / Embedding 网关地址	`http://6.86.80.4:30080/v1`
`RAGAS_JUDGE_MODEL`	RAGAS Judge 默认模型	`gpt-5`
`RAGAS_EMBEDDING_MODEL`	Embedding 默认模型	`text-embedding-3-small`
`ALIBABA_ACCESS_KEY_ID` / `ALIBABA_ACCESS_KEY_SECRET`	阿里云 DocMind 凭据	dataset build 必填
`ALIBABA_ENDPOINT`	DocMind 服务域名	`docmind-api.cn-hangzhou.aliyuncs.com`
`DATASET_GENERATOR_MODEL`	题库生成默认模型	`qwen3.6-plus`
`SCORE_API_TOKEN`	`/api/score` Bearer 鉴权令牌	留空则不鉴权
`RAGAS_METRIC_TIMEOUT_SECONDS`	RAGAS 指标计算超时	`300`（7指标建议值）

9. 技术栈

从依赖声明、Web 服务实现与测试代码来看，项目的技术栈如下。

后端 Python 3.12 · FastAPI · RAGAS 0.4.3 · Pydantic v2 · uvicorn AI / ML OpenAI SDK · LangChain · ragas · instructor 风格结构 文档解析 阿里云 DocMind 前端 Vanilla JS · Chart.js 风格报告页测试 pytest · FastAPI TestClient 工具链 uv · pyproject.toml · YAML 场景驱动

依赖声明

pyproject.toml 中列出了 ragas==0.4.3、langchain-openai、datasets、pydantic-settings、阿里云 DocMind SDK 等核心依赖。

Web 生态

控制台基于 FastAPI + 静态页面，服务器通过 webmain.py 配置日志和 uvicorn，前端报告页结合图表与表格展示历史 run。

测试现状

仓库同时存在 pytest 与 fastapi.testclient.TestClient 用例，涵盖 Pipeline、权重聚合、实时评分与 LLM 配置接口。

10. 目录结构

以下树状图概括了项目中最关键的源码、配置、数据、输出与测试位置。

siemens_ragas/
├── README.md
├── pyproject.toml
├── main.py
├── webmain.py
├── deploy.sh
├── .env.example
├── apps/
│   ├── pdf_question_bank/
│   ├── sample_python/
│   └── siemens_pdf_qa/
├── datasets/
│   ├── raw/
│   └── normalized/
├── docs/
├── outputs/
├── scenarios/
│   ├── online/
│   ├── offline/
│   └── siemens_build/
├── tests/
│   ├── webapp/
│   ├── test_pipeline.py
│   ├── test_weights.py
│   └── test_webapp_report_builder.py
├── rag_eval/
│   ├── adapters/
│   ├── advisor/
│   ├── config/
│   ├── datasets/
│   ├── dataset_builder/
│   │   ├── generator/
│   │   └── parser/
│   ├── execution/
│   ├── metrics/
│   ├── reporting/
│   └── shared/
└── webapp/
    ├── api/
    ├── services/
    └── static/
        ├── css/
        └── js/

源码主路径

rag_eval/ 是平台核心，webapp/ 负责服务端 API 与控制台，apps/ 放置面向不同业务应用的 adapter。

配置与产物

scenarios/ 维护 YAML 场景，datasets/ 存放原始/规范化数据，outputs/ 产出评测运行结果与 dataset build 工件。