需求 → 数据资产 智能匹配系统

FastAPI · BM25 + 向量混合检索 · 交叉编码器精排 · 可标定判决器的智能体闭环 · MCP

系统接收自然语言描述、需求截图或任意版面的 Excel，在数据资产目录中匹配可用的表， 输出带字段级依据的推荐方案。

匹配过程是智能体闭环，而非单向调用。每轮检索完成后，判决器逐条评估候选资产与需求的 相关性；未达门槛时，系统依据检索中间态的诊断结论自主选择纠偏动作并重新检索。目录中 确无可支撑的资产时，输出无法支撑的判定与依据，不以近似结果填充。用户可针对返回 结果提出修正意见，系统在保留既往判决上下文的前提下继续迭代。

智能体闭环

自我审阅

每轮检索后，判决器逐条判定候选与需求的相关性（相关 / 部分相关 / 不相关），由代码聚合 为分数并与门槛比较；未达门槛则进入纠偏。

match（检索）→ judge（逐条判相关性）→ 达标？
                                      ├ 是 → 交付
                                      └ 否 → 选纠偏动作 → 重新检索 → 再判

自主纠偏：可调整检索策略，不可调整判定标准

纠偏动作取自固定清单，权限边界由代码约束，不依赖提示词自律：

放开判定阈值等同于允许模型降低验收标准以使结果成立，将使"无法支撑"判定失效， 因此不纳入可调白名单，并由测试约束。

归因有据

纠偏前，代码从检索中间态计算带证据的诊断结论并提交判决器。同一现象往往对应两种病因 且处置方向相反，诊断的作用即在于区分二者：

多轮协作

• 解析后确认：抽取结果先交用户核对与增删，确认后再进入检索——纠错成本最低的环节 置于最上游

• 结果后追问：用户提出修正意见后，智能体携带既往会话历史继续纠偏，不重置上下文

• 会话持久化：会话状态落盘，服务重启后 session_id 仍然有效

可审计、可中断

每一步记录 action / reason / verdict / effect（执行动作、决策依据、判决原文、前后 差异），随结果一并返回。首个动作固定为完整检索，因此任一时刻中断均有可交付结果， 最坏情况等价于纯检索。长任务支持协作式取消。

判决器须先标定

判决器进入自动决策链前，需以人工金标测量其与真实优劣的一致性（Cohen's κ）， κ > 0.6 方可用于自动决策。更换模型、修改提示词或调整计分规则后须重新标定。

Related MCP server: MCP RAG Agent Server

自主优先级推荐

相关度与资产优先级（是否已订购、资产类型、数仓层级）量纲不同，直接加权需要人工调参， 且权重会随数据分布漂移而失效。系统改用自然断点分档 + 档内字典序，档宽由数据决定：

1. 估计可分辨最小差异（JND）：取本次查询候选相关度降序后正间隙的中位数 ρ， 回答"这条查询里典型的分数差有多大"；

2. 自然断点切档：从当前最高分向下扩展，直到遇到 间隙 > gap_factor × ρ 的显著 断层才切开。分数紧簇（近乎并列）不切档，由优先级决定顺序；存在明显断层时相关度主导；

3. 档内硬排序：按【优先级最差优先向量 → 相关度 → 覆盖度 → 表数更少】字典序选出。 组合方案的档位取成员最低档，避免一张高档表把低档成员一并抬高。

档宽随数据自适应，不按查询形态预设分支——把"用户在问什么"交给预写的 if-else， 与手工权重是同一类问题。

优先级档位由「是否已订购 + 资产类型 + 数仓层级」按字典序合成，映射全部来自配置：

# config/config.yaml → matching.ranking.priority
ordered_rank: 6         # 已订购（由订购清单 vlookup 标记，最高档）
asset_type_rank: {...}  # 资产类型 → 档位
layer_only_types: [...] # 仅这些类型内部再按数仓层级细分
layer_rank: {DWA: 5, DIM: 5, DWV: 4, DWI: 3, ODS: 2, STG: 1}

# config/config.yaml → matching.layering
gap_factor: 2.0         # 间隙达 JND 几倍算断层：越大同档越宽，越偏向优先级
min_jnd: 0.02           # JND 绝对下限，仅兜底分数全等 / 单点等退化情形

其它能力

快速开始

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 可选：安装后启用语义召回 / 精排 / 本地大模型；未安装则自动降级为词法检索 + 规则解析
pip install sentence-transformers
pip install torch --index-url https://download.pytorch.org/whl/cpu

python -m uvicorn src.api.app:app --host 127.0.0.1 --port 8001

Web 面板位于 http://127.0.0.1:8001。接口调用：

# 一步式：解析 → 检索 → 自我审阅 → 交付
curl -X POST http://127.0.0.1:8001/api/agent/run \
  -F "text=分析会员复购行为，需要用户ID、订单数、支付金额"

# 多轮：对上一轮结果提出修正意见，携带历史继续纠偏
curl -X POST http://127.0.0.1:8001/api/agent/resume \
  -F "session_id=<上一轮返回的 session_id>" \
  -F "feedback=当前结果不符合预期，需要履约时效相关的资产"

示例目录随仓库提供（data/samples/，3000 张表，覆盖交易、用户、商品、履约、营销、 服务、风控、内容、位置、财务十个业务域），无需额外准备数据；CPU 环境同样可运行。

首次请求会构建检索索引并加载模型——3000 张表在 CPU 上需数分钟；索引落盘至 data/.cache/，之后按内容指纹命中缓存，重启不重建。

换成自有数据

系统对被推荐对象的类型不做硬编码假设：只要数据可整理为"条目 + 属性清单 + 描述"的 结构即可直接使用。数据表、文档库、商品、API、知识条目均适用，无需改动检索、排序 与智能体骨架。

1. 必换：目录数据

准备一份同结构 CSV（示例见 data/samples/assets.sample.csv）：

# config/config.yaml
data:
  assets_file: data/自有目录.csv      # 默认按 gb18030 读取

默认读取编码为 gb18030。若目录文件为 UTF-8，可先行转码，或修改 src/data_loader.py 中的读取编码——该处是唯一与文件编码相关的耦合点。

枚举取值必须与排序逻辑对齐。 资产类型 / 层级 / 周期 三列参与优先级分档与硬 过滤，取值须出现在对应映射表中，否则该行会落到最低档或永远无法被筛中：

替换目录后，将自有取值补进上述映射表，或将数据归一到既有取值，二选一。 数据域 需保持单一粒度（同一层级的枚举），混用粗细粒度会使按域过滤漏掉子类。 仓库内示例目录已按此对齐。

ordered_rank（已订购）依赖 data.ordered_file 指向的订购清单；示例配置未提供该文件， 该档位不会触发，接入自有清单后自动生效。

2. 建议更换：四份领域词表（直接影响召回质量）

仅同义词表可通过 data.synonyms_file 换路径；后三者的路径写死在 pipeline.py 与 normalize.py 中，按原路径替换文件内容即可。仓库内的四份均为起步规模（同义词 8 组、 分类 64 条、专名 67 条），按自有领域扩充。

其中同义词表收益最高。格式为 {"规范词": ["别名1", "别名2"]}，将目录字段名中同一 概念的不同写法归为一组即可；先覆盖十余组高频概念即可见效。

3. 可选：替换抽取提示词中的示例

src/matching/extractor.py 与 src/matching/llm_parser.py 的提示词中包含领域示例， 用于界定"何为一条需求、何为一个字段"。示例不构成逻辑分支；但在领域差异较大时， 替换为本领域的两三个示例可显著提升解析质量。

4. 更换后必须重新标定

• 语义阈值：field_match.retrieve_min_sim 与 min_ce 属模型校准项，取值随嵌入 模型与领域词汇分布变化。从本领域各取十余对"真同义"与"无关"字段，按两组分数的分界定值。

• 判决器 κ：相关性判定依赖领域语义，跨领域沿用旧结论无效。以本领域标注集重新测量 Cohen's κ，仍需 > 0.6 方可用于自动决策。

• 评测集：仓库不含金标标注。指标须在本领域自建标注集上重新建立，跨领域数字不可比。

三种接入

• Web：/ 单页，描述需求 → 确认草稿 → 生成方案 → 导出 Excel，支持多轮修正与 任务取消

• REST：/api/agent/run（一步式）、/api/agent/resume（多轮追问）、/api/match （纯检索）、/api/parse + 确认（两步式）；含文件的请求自动转为异步任务，支持取消

• MCP：/api/mcp/，六工具（parse_requirement / revise_draft / match_assets / refine_results / submit_feedback / list_asset_facets）+ 异步任务 + 协作取消， 对话平台可自动发现工具

完整调用契约见 docs/API接口文档.md。

文档

工程原则

• 语义判断交由模型，机械切分交由代码；不对需求文档的版面做硬编码假设

• 不做静默降级：截断、丢弃与能力降级一律经 /api/health 或诊断通道上报

• 判决器进入自动决策链前必须标定；能力升级仅通过配置实现，不改动代码

• 每个已修复缺陷均附带回归测试，并记录其原始失效方式

说明

本仓库提供可复用的方法与工程骨架。所含目录数据为构造的通用样本（3000 张表，结构与 统计分布与真实生产目录对齐）；词表与评测数据经脱敏后完整提供。真实业务目录不包含在 内，替换为自有数据即可运行。