diff --git a/project-overview.html b/project-overview.html new file mode 100644 index 0000000..b029a26 --- /dev/null +++ b/project-overview.html @@ -0,0 +1,1101 @@ + + + + + + Siemens RAGAS 项目总览 + + + + +
+ + +
+
+ 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_builderrag_eval/dataset_builder/PDF解析、source chunk 归一化、LLM 题目生成、草稿题库与构建产物写出。
executionrag_eval/execution/评估编排、在线/离线模式切换、adapter 调用、RAGAS 打分与结果聚合。
metricsrag_eval/metrics/RAGAS 指标注册、模型构建、评估管道装配、指标权重与文档权重聚合。
reportingrag_eval/reporting/运行产物写入、summary 生成、metadata 与 scenario 快照沉淀。
adaptersrag_eval/adapters/HTTP/Python 应用适配器封装，把外部应用结果统一为 answer / contexts / raw_response。
webappwebapp/FastAPI Web 控制台、OpenAPI 文档、任务后台管理、场景扫描、历史报告查询。
appsapps/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/scoreDify 实时评分接口，接收单条问答并返回各指标得分与综合得分。
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 部署步骤

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

常用命令

+ 
# 依赖安装
+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_KEYOpenAI 兼容接口凭据your-api-key
OPENAI_BASE_URL统一 LLM / Embedding 网关地址http://6.86.80.4:30080/v1
RAGAS_JUDGE_MODELRAGAS Judge 默认模型gpt-5
RAGAS_EMBEDDING_MODELEmbedding 默认模型text-embedding-3-small
ALIBABA_ACCESS_KEY_ID / ALIBABA_ACCESS_KEY_SECRET阿里云 DocMind 凭据dataset build 必填
ALIBABA_ENDPOINTDocMind 服务域名docmind-api.cn-hangzhou.aliyuncs.com
DATASET_GENERATOR_MODEL题库生成默认模型qwen3.6-plus
SCORE_API_TOKEN/api/score Bearer 鉴权令牌留空则不鉴权
RAGAS_METRIC_TIMEOUT_SECONDSRAGAS 指标计算超时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 工件。

+
+
+
+ +
+ Generated for siemens_ragas · Self-contained HTML overview · Siemens teal/blue documentation theme +
+
+
+
+ + + +