目录
master
分支1
标签0
+ 疑修
Web IDE
20000786
Update README before GitLink upload
2天前2次提交
README.md

PolicyEvidence

PolicyEvidence 是一个面向企业制度、政策文件、采购合规、合同条款和办事指南的证据约束 RAG 工作台。它把资料上传、条款级检索、证据约束回答、断言校验、AI Skill、MCP 工具和后端审计留痕做成一个可部署、可解释、可被智能体复用的工程化应用。

这个项目的目标不是做一个聊天 Demo，而是提供一个能在企业制度问答、内控审查、资料补证、外部 Agent 工具接入等场景中直接落地的工作台。

核心价值

  • 真实可用：用户上传自己的制度、合同、政策、招标文件后，系统只基于上传资料回答。
  • 可解释：答复会展示结论、摘要、证据片段、断言支持情况、风险提示和资料缺口。
  • 能力分层清晰：RAG 负责自由问答，AI Skill 负责流程化业务任务，MCP 负责外部智能体工具接入。
  • 沐曦算力可见：支持 Gitee AI / 沐曦 OpenAI-compatible 接口，前端有模型连接检测、模型状态和最近延迟。
  • 开源友好：上传资料、索引、调用日志、构建产物和密钥配置默认不提交；路径均按项目根目录解析，不依赖固定盘符。

功能概览

  • 文档上传与删除：支持 PDF、Word、Excel、PPT、HTML、Markdown、TXT、CSV、JSON 等常见格式。
  • 自动索引：上传后自动解析、清洗、条款级分片并同步知识库。
  • RAG 问答：面向自由问题，完成证据检索、上下文约束和可追溯答复。
  • RAG 诊断：检查资料覆盖度、知识缺口和下一步补证建议。
  • AI Skill：面向固定业务流程，例如合规审查、断言校验、证据报告、证据链路和多代理协同。
  • MCP 工具：暴露标准化工具，支持外部智能体调用。
  • 后端审计：记录 API、RAG、LLM、Skill、MCP 调用留痕和延迟，前端默认不展示日志。

技术栈

  • 前端：Vue 3 + TypeScript + Vite
  • 后端：FastAPI + Pydantic + OpenAI-compatible SDK
  • RAG：文档解析、条款级切分、BM25/字符向量/规则融合检索、证据约束生成、Claim-Level 校验
  • MCP：HTTP 调用接口 + stdio MCP Server
  • AI Skill：项目内置 Skill 描述 + 后端可运行 Skill Registry

目录结构

backend/                  FastAPI 后端、RAG、MCP Server、Skill Registry
frontend/                 Vue 工作台前端
skills/                   可开源的 AI Skill 描述与示例
samples/                  可用于演示上传的样例 PDF
data/eval_questions/      评测问题集
data/uploads/             用户上传资料，运行时生成，默认不提交
data/processed_uploads/   RAG 分片索引，运行时生成，默认不提交
data/call_logs/           调用日志，运行时生成，默认不提交
.env.example              后端模型和路径配置示例
frontend/.env.example     前端 API 代理配置示例
LICENSE                   开源许可证

环境要求

  • Python 3.10+
  • Node.js 18+
  • npm 9+

推荐先在项目根目录创建 Python 虚拟环境。下面所有命令都使用相对路径，不要求项目放在 D 盘或任何固定目录。

快速启动

1. 获取代码

git clone <url>
cd rag_project

如果你是直接解压源码包，进入解压后的项目根目录即可。

2. 配置后端环境

copy .env.example .env
cd backend
python -m pip install -e .

macOS / Linux:

cp .env.example .env
cd backend
python -m pip install -e .

没有配置模型也可以运行，系统会使用本地检索、摘要和断言校验给出保守结果。

3. 启动后端

cd backend
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Windows 也可以在项目根目录直接运行：

backend\start_backend.cmd

健康检查：

http://127.0.0.1:8000/api/health

FastAPI 交互文档：

http://127.0.0.1:8000/docs

4. 启动前端

新开一个终端：

cd frontend
npm install
npm run dev

Windows 也可以在项目根目录直接运行：

frontend\start_frontend.cmd

默认访问：

http://127.0.0.1:5173

5. 上传样例文档测试

项目提供了一个可公开提交的样例文件：

samples/enterprise_policy_sample.pdf

打开前端后，在左侧上传该 PDF，等待同步完成，然后分别测试：

  • RAG 问答：请总结已上传资料的核心要求。
  • RAG 诊断：资料是否足够回答报销材料要求？
  • AI Skill：选择合规审查、断言校验或证据报告。
  • MCP 工具：选择证据检索或工具问答。

模型与沐曦算力配置

复制 .env.example 为 .env，填入 Gitee AI / 沐曦算力的 OpenAI-compatible 配置：

POLICYEVIDENCE_LLM_BASE_URL=https://ai.gitee.com/v1
POLICYEVIDENCE_LLM_API_KEY=<your-api-key>
POLICYEVIDENCE_LLM_MODEL=<model-name>

例如沐曦/Gitee AI 可按实际开通模型填写 MiniMax-M2.7 或平台提供的其它 OpenAI-compatible 模型名。

常用可调参数：

POLICYEVIDENCE_LLM_TIMEOUT=30.0
POLICYEVIDENCE_LLM_TEMPERATURE=0.7
POLICYEVIDENCE_LLM_TOP_P=0.7
POLICYEVIDENCE_LLM_TOP_K=50
POLICYEVIDENCE_LLM_FREQUENCY_PENALTY=1.0
POLICYEVIDENCE_LLM_MAX_TOKENS=1024
POLICYEVIDENCE_LLM_STREAM=true
POLICYEVIDENCE_LLM_FAILOVER_ENABLED=true

模型名称不写死在前端。页面右上角和底部状态栏显示的是后端 /api/model/status 返回的 model 字段，也就是 .env 中的 POLICYEVIDENCE_LLM_MODEL。未配置时会显示“未连接模型”。

启动后点击前端右上角 检测连接，可以看到模型是否配置、是否连通、当前模型名称和最近调用延迟。

前端 API 配置

默认前端请求 /api，由 Vite 代理到后端 http://127.0.0.1:8000。如果后端端口不是 8000，可以复制前端配置：

cd frontend
copy .env.example .env

然后修改：

VITE_API_BASE=/api
VITE_API_PROXY_TARGET=http://127.0.0.1:8001

生产部署时也可以把 VITE_API_BASE 设置成完整后端地址，例如：

VITE_API_BASE=https://your-domain.example.com/api

数据目录与路径规则

默认运行时目录：

data/uploads/             用户上传资料
data/processed_uploads/   RAG 分片索引
data/call_logs/           后端调用日志

这些目录只保留 .gitkeep，真实文件默认被 .gitignore 忽略。项目不会默认读取旧演示目录，也不会要求放在 D 盘。

如需修改目录，在 .env 里写相对路径或绝对路径。相对路径会按项目根目录解析：

POLICYEVIDENCE_RAW_DOCS_DIR=data/uploads
POLICYEVIDENCE_PROCESSED_DIR=data/processed_uploads
POLICYEVIDENCE_CALL_LOGS_DIR=data/call_logs

能力边界

三类能力的定位不同，前端也按这个边界拆开：

  • RAG 问答层：适合一次性的自然语言问题。它负责“检索证据 + 约束大模型回答”，输出答复、引用证据和断言支持情况。
  • AI Skill 流程层：适合可复用业务任务。它把检索、校验、生成、报告整理等步骤固化成流程，例如合规审查会稳定输出风险点、缺失材料和控制建议。
  • MCP 工具层：适合外部智能体调用。它不是给普通用户再做一个问答入口，而是把检索、问答、审查、诊断等能力标准化为 tool，供 Codex、Claude Code、OpenCode 等 Agent 复用。

AI Skill

项目提供两层 Skill 能力。

第一层是可开源的 Skill 描述，位于 skills/：

  • policy_qa_skill：证据约束问答
  • compliance_check_skill：合规风险检查
  • claim_verify_skill：断言证据校验
  • evidence_report_skill：证据报告生成

第二层是后端可直接运行的 Skill Registry，可通过前端或接口调用：

GET  /api/skills
POST /api/skills/call

调用示例：

{
  "skill": "compliance_review",
  "arguments": {
    "scenario": "请审查下面这段业务事实是否符合已上传制度。",
    "top_k": 6,
    "strict": true
  }
}

前端默认面向普通用户展示的 Skill 是流程化业务能力：

  • claim_verification
  • evidence_report
  • compliance_review
  • evidence_graph
  • agent_workflow

后端 Skill Registry 还保留 answer_with_evidence、evidence_search、rag_diagnostics、call_audit 等底层能力，方便接口测试、验收审计和智能体编排；前端把这些归入 RAG/MCP 或后端审计边界，避免普通用户混淆。

MCP 服务

HTTP MCP

GET  /api/mcp/tools
POST /api/mcp/call

调用示例：

{
  "tool": "search_evidence",
  "arguments": {
    "query": "报销需要提交哪些材料",
    "top_k": 5
  }
}

常用 MCP tools：

  • get_system_snapshot
  • list_documents
  • search_evidence
  • answer_with_evidence
  • verify_claims
  • build_evidence_report
  • run_compliance_review
  • diagnose_rag
  • build_evidence_graph
  • list_invocation_logs（后端审计能力，前端默认隐藏）
  • list_skills
  • list_agents
  • run_a2a_workflow
  • reload_knowledge_base

stdio MCP Server

智能体客户端可以启动：

cd backend
python -m app.mcp_server.server

该 Server 支持：

  • tools/list
  • tools/call
  • resources/list
  • resources/read
  • prompts/list
  • prompts/get

主要 API

GET    /api/health
GET    /api/model/status
POST   /api/model/test
GET    /api/knowledge/documents
POST   /api/knowledge/upload
DELETE /api/knowledge/documents/{doc_id}
GET    /api/knowledge/tasks/{task_id}
POST   /api/retrieve
POST   /api/chat
POST   /api/compliance/check
POST   /api/rag/diagnose
POST   /api/rag/graph
GET    /api/logs
GET    /api/skills
POST   /api/skills/call
GET    /api/mcp/tools
POST   /api/mcp/call
GET    /api/a2a/agents
POST   /api/a2a/run
GET    /api/eval/datasets
POST   /api/eval/run

可解释性设计

每次问答会尽量返回：

  • verdict：整体判断
  • summary：可直接阅读的摘要
  • citations：引用证据片段
  • claims：断言支持/弱支持/不支持状态
  • workflow：检索、校验、生成、审计流程
  • trace：召回数量、覆盖度、严格模式、耗时等追踪信息

前端不会把原始 JSON 直接丢给普通用户，而是转换成业务化的答复、风险点、材料清单和证据卡片。调用日志保留在后端，用于接口验收和问题追踪。

评测

项目内置小型评测集：

data/eval_questions/

运行评测：

GET  /api/eval/datasets
POST /api/eval/run

评测输出包括关键词命中率、证据命中率、Claim 支持率和延迟。开源后可以继续扩展更多行业数据集。

常见问题

启动后 WinError 10013 怎么办？

通常是端口被占用、被系统保留，或权限策略限制。换一个端口即可：

cd backend
python -m uvicorn app.main:app --host 127.0.0.1 --port 8001

然后在 frontend/.env 中设置：

VITE_API_PROXY_TARGET=http://127.0.0.1:8001

为什么上传后才显示资料数量？

系统默认只使用 data/uploads/ 中的用户上传资料，避免开源项目自带演示文件影响真实业务判断。

模型未配置还能使用吗？

可以。系统会使用本地检索、摘要和断言校验给出保守结果；配置模型后会得到更自然的生成式答复。

MCP 和 Skill 是否只是展示？

不是。前端可以直接运行 Skill/MCP，后端也提供 /api/skills/call、/api/mcp/call 和 stdio MCP Server；调用留痕保存在后端，便于验收和排障。

关于

面向企业制度、政策文件和合规审查的证据约束RAG工作台，集成AI Skill、MCP工具、文档上传索引、可解释问答和沐曦/Gitee AI模型调用。

README.md
308.0 KB
MIT
邀请码
    Gitlink（确实开源）
  • 加入我们
  • 官网邮箱：gitlink@ccf.org.cn
    • QQ群
  • QQ群
    • 公众号
  • 公众号

版权所有：中国计算机学会技术支持：开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号