把企业材料转换成可核对、可追溯的表单候选答案；证据不足、相互冲突或格式不符时，系统会停止自动填写并交给人工确认。
| 能力 | 解决的问题 |
|---|---|
| 混合检索 | BM25、Embedding、pgvector、重排与可选 LightRAG 共同召回候选，并保留各通道排名轨迹。 |
| 缺口驱动的递进检索 | 先解析问题中的实体、时间、指标、格式和标准编号；证据链缺少哪个槽位，就针对缺口扩大范围继续检索。 |
| 生成前充分性门禁 | 候选必须组成完整、相互绑定且在模型可见上下文中的证据链，否则直接返回 review、no_answer 或 conflict。 |
| 多格式保真填表 | 读取知识材料，定位 Markdown、Word、Excel、CSV、JSON 表单字段，保留原位置、样式、公式和未决占位内容。 |
系统不是通用聊天机器人。模型只能使用本次检索得到的材料；自动答案必须带原文引用、页码或行号、文本块 ID 和来源定位。
flowchart LR
A[企业材料] --> B[解析 / OCR / 分块]
B --> C[BM25 + Embedding + pgvector]
F[待填表单或问题] --> D[结构化约束解析]
C --> E[候选证据]
D --> E
E --> G{证据充分?}
G -- 否: 提取缺口 --> H[定向扩展范围并再次检索]
H --> E
G -- 是 --> I[受约束生成与引用校验]
I --> J{引用、冲突、格式门禁}
J -- 通过 --> K[候选答案 / 保真写回]
J -- 不通过 --> L[人工复核]
默认链路为：结构化问题约束 → 混合检索 → 证据槽位充分性判断 → 缺口驱动递进检索 → 覆盖保护 shortlist → 模型可见证据复检 → 生成与引用校验。组件均通过端口和适配器接入，便于替换向量库、Embedding、重排器、规划器、充分性判断器或模型。
需要 Python 3.10 或更高版本。默认路径不会调用外部付费模型；模型端点必须显式配置。
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
python -m pip install --no-deps -e .
ragform migrate
cp configs/lightrag-mix-v1.env.example configs/lightrag-mix-v1.env
# 编辑本地配置后加载环境变量
set -a && source configs/lightrag-mix-v1.env && set +a
ragform serve --host 127.0.0.1 --port 11114打开 http://127.0.0.1:11114，OpenAPI 位于 http://127.0.0.1:11114/docs。本地默认账号见 .env.example，部署前必须替换其中的示例凭据。
| 用途 | 格式 | 保留的信息 |
|---|---|---|
| 知识材料 | TXT、Markdown、PDF、DOCX、CSV、JSON、XLSX/XLSM、HTML、PPTX | 页码、章节、行号、单元格、工作表、幻灯片与来源哈希 |
| 待填表单 | Markdown、JSON、CSV、XLSX/XLSM、DOCX | 字段锚点、原位置哈希、样式、公式、其他工作表与未决占位符 |
DOCX 使用 python-docx，Excel 使用 openpyxl，PDF 使用 pypdf。格式识别先生成安全结构视图，再由同一诊断流程确认真正需要填写的位置。详细行为见架构说明。
retrieval.indexed-hybrid-v3在授权材料范围内融合关键词与向量召回。query-planner.core-v1不猜题型，只登记问题表面明确出现的编号、时间、版本和格式。sufficiency.retrieval-prerequisites-v1只判断检索前置条件，不把关键词共现冒充语义充分；最终支持度由生成和独立证据验证组件判断。retrieval.progressive-v2根据缺失槽位定向扩展候选范围；定向扩展没有新增时，恢复到调用方授权的完整语料范围。- 生产链不存在引用补全器或运行时题目策略；模型引用必须原样通过通用校验。
- 填表和单问题共用
form-core-v1：只保留“仅用证据、完整覆盖、精确引用、不足拒答、冲突上报”五项核心契约；非提取型答案必须通过独立证据验证。
无证据、证据冲突、低 OCR 置信度、非法引用、模型失败或模型可见上下文缺少必要 witness 时，系统均 fail closed。详细组件契约见组件注册表，检索与门禁设计见架构说明。
复杂公开语料包含 808 份材料、9 种格式、22,999 个文本块和 96 道开发题，覆盖单文档时间冲突、跨文档年度冲突、标准替代关系和多格式材料。
旧版 96 题结果已撤回为“历史调试回归”，不能作为当前系统指标：当时默认 v4 策略包含题目对应的布尔答案和 RFC 编号映射，既有保留集也复用了开发集题型模板并已被反复查看。当前 core-v1 代码尚未产生新的端到端准确率；README 不再展示容易被误解为泛化能力的 94/96 或 96/96。
真实发布仍需新的独立保留集、真实业务模板、人工金标和完整部署验收。语料、历史结果、失败归因和限制见复杂语料说明与验证记录。
此外，仓库已接入 ragform-hard-suite-v1：MultiHop-RAG、ContractNLI 与 WikiContradict 共 13,128 道问题，严格分离 train/dev/test、运行材料和评分标签。它用于多跳完整证据召回、合同支持/冲突/未提及判断和真实知识冲突测试；公开 test 仍不能替代私有未见发布保留集。详见外部高难度 RAG 基准。
主要 API：POST /api/documents/upload、POST /api/questions/answer、POST /api/forms/upload、POST /api/forms/{id}/process、GET /api/jobs/{job_id}、GET /api/forms/{id}/export。完整接口以运行中的 OpenAPI 为准。
ragform ingest company.docx --kind knowledge
ragform form-create supplier.xlsx
ragform form-fill <form_id> --document <document_id>
ragform form-export <form_id> --format xlsx --output filled.xlsxmake check
make test
make verify-form-data测试覆盖检索、证据充分性、递进范围扩展、引用门禁、模型重试、租户隔离、数据库迁移、API、多格式解析与保真写回。发布声明边界见验证记录。
| 位置 | 内容 |
|---|---|
src/rag_system/ |
核心领域、流程编排、可替换适配器、API 和前端 |
data/ |
公开材料、表单任务、隔离金标和复杂语料边界 |
docs/ |
架构、组件、评测、部署、运维和审核文档 |
deploy/ |
Compose、Kubernetes、Prometheus 和 systemd 模板 |
configs/ |
基线、混合检索和本地模型配置示例 |
scripts/ |
数据构建、导入、评测、迁移和真实链路检查 |
tests/ |
单元、集成、浏览器和安全边界测试 |
baselines/ |
冻结基线清单 |
.github/ |
GitHub 依赖更新配置；发布工作流模板位于 deploy/ |
- 不提交真实企业合同、个人信息、API Key、SQLite 运行库或上传文件。
- 公开数据和评测标签不会随服务启动自动导入，也不会进入运行时检索提示词。
- 原合同与制度核验接口是兼容模块，
passed/failed不构成法律意见。 - 当前仓库尚未声明开源许可证；在许可证明确前，请勿假定代码可被任意再分发。