本项目是一个本地运行的 RAG 评测产品。它把资料导入、知识库切分与索引、Workflow 编排、Query 评测集生成、RAGAS 评测和外部 HTTP 调用放在同一个控制台里，适合用来快速验证一个 RAG 系统是否“能检索、能回答、能评测、能被其他程序调用”。
默认语言是中文；默认模型服务商是千问。
- 导入自己的资料包：支持
.txt、.md、.html、.pdf、.docx和单页 URL。 - 管理本地知识库 DB：资料会解析、切分成 chunks，并写入本地 Chroma 向量库。
- 搭建 Workflow：用画布保存自己的 Graph，也可以从空白、离线建库、RAG、评测模板开始。
- 生成 query-only 评测集：输入 3-5 个示例 Query，模型会结合知识库内容生成更多 Query。
- 做无参考答案评测：默认使用不依赖标准答案的 RAGAS 指标。
- 对外提供 Runtime API：其他语言可以通过 HTTP/JSON 调用某个 RAG Graph 的输入输出。
建议使用 Python 3.10+。
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
.venv/bin/python -m playwright install chromium安装前端依赖：
cd frontend
npm install
cd ..首次启动或首次读取配置时，系统会自动从模板生成本地配置：
config/application.yamlconfig/model_roles.yaml
这两个运行时 YAML 会被 Git 忽略；仓库只跟踪 .example 模板。需要重置配置时，删除本地 YAML 后重启服务即可重新生成。
默认配置只需要一个千问 Key：
export API_KEY_QWEN="your-api-key"Windows 当前会话：
set API_KEY_QWEN=your-api-key默认模型角色：
- Embedding：
text-embedding-v4 - Answer：
qwen3.7-plus - Judge：
qwen3.7-plus
如需修改模型或 Provider，可以在产品里的「配置」页调整，也可以直接编辑：
config/application.yamlconfig/model_roles.yaml
.venv/bin/python -m uvicorn rag_eval.api.app:app --host 127.0.0.1 --port 8000健康检查：
curl http://127.0.0.1:8000/api/health另开一个终端：
cd frontend
npm run dev -- --port 5173打开：
http://127.0.0.1:5173/
进入「配置」页，确认默认 Provider 和三个模型角色：
- Embedding：用于把 chunks 写入向量库。
- Answer：用于 RAG 回答。
- Judge：用于 RAGAS 评测。
第一版默认只保留千问，普通使用无需新增 Provider。
进入「数据」页：
- 选择「知识库」。
- 创建一个知识库。
- 导入资料：选择本地文件，或粘贴一个 URL。
- 导入完成后构建索引。
说明：
.doc暂不支持，请先转成.docx。- URL 会用独立浏览器打开原页面并提取可见正文；登录页、验证码页或强反爬页面可能失败。
- Chunk size / overlap 放在「高级设置」里，默认值通常可以直接使用。
进入「Workflow」页后，先选择：
- 加载已有 Graph
- 新建 Graph
新建 Graph 可以选择：
- 空白
- 创建离线数据库
- 进行 RAG
- 评测
保存 Graph 不要求它立刻可运行；执行前才会做可执行性校验。一个可被 Runtime API 调用的 RAG Graph 通常需要从 Start 接收 question，经过 Retrieve -> Prompt / LLM -> Answer，最后到 End。
进入「数据」页的「评测集」：
- 选择一个知识库 DB。
- 输入 3-5 个示例 Query。
- 点击生成。
模型会结合知识库 chunks 和示例 Query 的风格生成 query-only 数据集，不生成 reference answer。
进入「评测」页：
- 选择 Query 集。
- 选择一个可回答 Query 的 RAG Graph。
- 点击运行评测。
query-only 评测默认使用 reference-free 指标，例如：
faithfulnessanswer_relevancy
只有样本包含 ground_truth / reference 时，才适合使用 context precision / recall 这类依赖参考答案的指标。
进入「导航」页的第 6 步「部署 API 调用」，点击「一键部署」后，会展示：
- Runtime API 服务地址
- Contract version
- 可调用 Graph 列表
- 某个 Graph 的输入 JSON
- 输出 JSON
invoke/batch的 curl 示例
Runtime API 只暴露可从 question 执行到 Answer 的 RAG Graph。离线建库和评测 Graph 不会作为外部 invoke 目标。
curl http://127.0.0.1:8000/api/runtime/capabilitiescurl http://127.0.0.1:8000/api/runtime/workflowscurl -X POST http://127.0.0.1:8000/api/runtime/workflows/1/invoke \
-H 'Content-Type: application/json' \
-d '{"question":"如何导入文档？"}'成功响应结构：
{
"ok": true,
"output": {
"question": "如何导入文档？",
"answer": "模型生成的答案",
"contexts": ["检索命中的上下文"]
},
"metadata": {
"workflow_id": 1,
"knowledge_base_id": 1,
"collection_name": "kb_1_docs",
"top_k": 3,
"context_count": 1
}
}curl -X POST http://127.0.0.1:8000/api/runtime/workflows/1/batch \
-H 'Content-Type: application/json' \
-d '{"questions":["如何导入文档？","如何运行评测？"]}'第一版是单用户本地产品，没有登录、权限和多租户。
常见本地数据：
- SQLite 状态库：默认在
var/app下。 - 上传原文件：保存到本地应用目录。
- Chroma 向量库：按配置或知识库 collection 落本地目录。
- 评测结果：保存在本地状态库，并可按旧脚手架配置输出 CSV。
这些目录通常属于本地运行产物，不应该提交到 Git。
如果你只想跑旧的命令行 demo，仍可以使用：
python quickstart.py旧 Streamlit 控制台仍保留：
streamlit run streamlit_app.py但当前主产品入口是 React + FastAPI：
http://127.0.0.1:5173/
frontend/ # React + React Flow 产品前端
rag_eval/api/ # FastAPI HTTP API
rag_eval/ingestion/ # 文件 / URL 解析、chunk 生成
rag_eval/workflow/ # Graph 校验与执行
rag_eval/query_generation.py
rag_eval/vector/ # Chroma 向量库构建与管理
rag_eval/eval_engine/ # RAGAS 评测
rag_eval/storage.py # SQLite 本地状态库
config/ # 模型、Provider、chunk、评测配置
tests/ # 后端单测与集成测试
后端测试：
.venv/bin/python -m pytest -q前端构建：
cd frontend
npm run build- 第一版是单机本地产品。
- URL 只做单页导入，不做站点爬取。
- 默认不替用户把搜索页换成其他搜索服务；用户给什么 URL，就解析这个 URL 本身。
- 默认评测走 query-only / reference-free 路径，避免空 reference 造成误导性分数。
- Runtime API 只负责调用已准备好的 RAG Graph，不隐式触发导入、切分、索引或评测。