105 lines
11 KiB
Markdown
105 lines
11 KiB
Markdown
# 可切换专项判断模块：Jev / 本地开源模型
|
||
|
||
日期：2026-09-28。状态：用户已明确可切换方向；本文件为工程设计候选，代码、配置加载和真实模型接入均未实现。对应 FR-JUD-01、BR-17–20、AC-17–21，并沿用 BR-05/09/12/13/16。
|
||
|
||
## 1. 产品职责与选择
|
||
|
||
模块负责回答“现有证据是否支持某个具体判断”，例如“提供的回款材料是否足以支持账期延长的解释”。输入同一套问题、经验适用条件、评价标准和证据；输出可被主审消费的结构化专项判断。历史经验归平台管理，不存成某一家模型的专有资产。
|
||
|
||
| 模式 | 实际执行方 | 凭据要求 | 对主审的作用 |
|
||
|---|---|---|---|
|
||
| jev | Jev 官方服务，通过专用适配器 | 有效 Jev 凭据及数据出口授权 | 提供局部判断，按统一契约返回 |
|
||
| local | 客户/开发环境部署的开源模型推理服务，通过本地适配器 | 无需 Jev Key；本地服务自己的认证按部署设置 | 执行同一业务任务，按统一契约返回 |
|
||
| disabled | 不执行专项模型调用 | 无需专项模型凭据 | 主审继续使用规则、工具和经验，标明专项核查未完成 |
|
||
|
||
默认关闭；有已验证的本地配置后，可显式选择或将其设为默认。不得因为缺少 Jev Key 阻止整个服务启动。此处关闭只关闭专项模块，主审自身仍需独立的可用模型配置。
|
||
|
||
本地方案替代的是专项模块的业务职责，不是复制 Jev 权重、训练方法或原生概率能力。不承诺两者逐题同答、评分相等或准确率相等；这些必须通过相同样本上的独立测评证明。Jev 是否支持私有化不在本设计假设内。
|
||
|
||
## 2. 架构与唯一职责
|
||
|
||
目标调用链（未实现）：主审提出具体问题 → 统一判断入口 → 配置/题型/数据出口检查 → 所选适配器 → 输出归一化与证据校验 → 主审综合意见 → 硬规则与完整性校验。
|
||
|
||
- `backend/contracts/prescreen.py` 拟定义共享题目、请求和结果；前端不得依赖厂商响应。
|
||
- `backend/services/judgment_provider.py` 拟负责路由、预算与归一化；Jev/local 各有专用适配实现，落点在 M3 按模块大小拆分，避免再造通用插件平台。
|
||
- 主审拥有整体研判；适配器没有写 recommendation 或审批状态的权限。
|
||
- 经验检索、证据来源、确定性计算和硬规则沿用平台能力，不因更换专项模型更换一套。
|
||
- 输出解释由主审结合经核验的证据形成，不假设供应商必定返回理由或可靠引用。本地模型生成的文字也不自动当作证据。
|
||
|
||
问题示例：题型 choice；选项 supported / contradicted / insufficient；要求只判断“材料是否支持所述解释”。这三个选项不是项目的通过/否决/补件状态。同一题目可由所选 Jev 或 local 执行，日常运行只调用选中的提供方；综合结论仍由主审形成。
|
||
|
||
## 3. 配置契约与运行选择
|
||
|
||
`JudgmentProfile` 由管理员在后端部署配置维护：
|
||
|
||
| 字段 | 类型 / 约束 |
|
||
|---|---|
|
||
| id / revision | 非空字符串1–128字符 / 正整数；修改生成新修订 |
|
||
| display_name | 非空字符串1–100字符 |
|
||
| provider | jev / local；disabled 不需要配置对象 |
|
||
| endpoint_ref | 后端已批准端点引用，不能由业务请求指定 URL |
|
||
| credential_ref | 可空密钥引用；jev 必需，local 按服务认证要求；不保存密钥值 |
|
||
| model_version / adapter_version / prompt_version / mapping_version | 非空版本标识；无自定义提示的适配填 not_applicable；若厂商无不可变模型修订则标 unresolved，不宣称可精确回放，生产启用前解决 |
|
||
| capabilities | choice / score / binary 的非空子集，表示已通过该配置验收的题型 |
|
||
| allowed_data_domains | demo / production 的非空子集，另叠加项目和调用者权限 |
|
||
| readiness | ready / unavailable；仅验证通过且配置完整者可为 ready |
|
||
|
||
P0 不提供在线修改配置接口。候选只读接口 `GET /api/prescreen/projects/{project_id}/judgment-profiles` 返回 `{profiles:[{id,revision,display_name,provider,capabilities}],default_profile_id:string?}`；只列对当前项目、调用者和数据域已获准且 ready 的配置，返回默认值也须通过相同过滤。无可用配置返回空列表和 null；不返回端点或凭据。项目无访问权限沿用 404 NOT_FOUND。
|
||
|
||
运行请求沿用 `enable_judgment:boolean=false`，新增 `judgment_profile_id:string?`：
|
||
|
||
1. 开关 false 且 ID 为空：冻结 provider=disabled，其余配置版本为空；不访问任一专项服务。开关 false 同时传 ID 属于 E-07 INVALID_REQUEST，避免静默忽略选择。
|
||
2. 开关 true：有 ID 使用指定的当前修订；无 ID 则解析后台默认。不存在/未获准/不可用/没有默认均返回 E-13，不静默关闭。服务启动不校验未选中的 Jev 密钥。
|
||
3. 入队前冻结配置修订和模型/适配/提示/映射版本，返回 ScreeningRun.judgment_config。幂等重放返回原运行，即使默认配置已变化也不重新解析。
|
||
4. 队列执行与每次发送前仍校验当前授权和撤销状态。冻结版本不赋予永久外发权限；版本被禁用/凭据被撤销则记 E-06，出口被撤销记 E-10；不改用新版本或其他提供方。
|
||
5. 配置切换须创建新运行；旧运行保持原记录。预算耗尽、限流或故障按详细设计重试上限处理，不做自动跨提供方回退。
|
||
|
||
## 4. 统一问题与请求
|
||
|
||
拟内部接口 `judge(request: JudgmentRequest, frozen_profile: JudgmentProfile) -> Judgment`；异常由统一入口转为约定错误，厂商原始异常不能直接返回浏览器。
|
||
|
||
`JudgmentRequest`：run_id、snapshot_id、question_id、question_version（共同 ID 约束），type:choice/score/binary，question:string[1..2000]，criteria:string[1..4000]，evidence_ids:string[0..20]，options:string[]，score_range:{min:number,max:number}?。调用者提交引用，后端从冻结授权快照提取对应证据文本，用户不能用 ID 夹带其他项目片段。
|
||
|
||
choice 要求 options 为2–20个唯一非空选项（各1–100字符）；score 要求有限 min<max、options为空；binary 要求两者为空。题目版本一经冻结不变；适配器可以转格式，但不能更换业务问题、证据、等级定义或增减事实。证据为空按缺证处理，不请求模型，返回 completed+unknown，并保留缺证原因；不把材料缺失解释为不支持。
|
||
|
||
本地适配器采用所选服务已经验证支持的结构化输出方法，随后进行服务端严格校验；不能依赖“请返回 JSON”的提示就宣称有结构保证。不能支持所需题型时 E-14，畸形输出 E-15；不让主审悄悄猜一个分数补齐。
|
||
|
||
## 5. 统一答案与供应商差异
|
||
|
||
`JudgmentAnswer` 使用可辨识联合：
|
||
|
||
| kind | 字段 | 校验 |
|
||
|---|---|---|
|
||
| choice | value:string | 必须属于该题冻结 options |
|
||
| score | value:number | 有限数值，且在该题 score_range 内 |
|
||
| binary | value:boolean | 仅表达该题命题是否得到支持，不表示审批通过 |
|
||
| unknown | reason_code:missing_evidence/inconclusive | 明确无法判断，不强制选择肯定或否定 |
|
||
|
||
正常答案 kind 与题型一致，unknown 对所有题型有效。结果字段见 [详细设计](03-detailed-design.md)：completed 必须有合法 answer；failed/skipped 的 answer 必须为 null；failed 必须有 error_code，skipped 必须有 skip_reason（disabled/not_configured/not_authorized/unsupported）。例如能力缺失为 skipped+unsupported，并附 E-14；传输/输出错误为 failed，分别 E-06/E-15。关闭时已计划的题目可记 skipped+disabled；无计划题目时运行级保留关闭标识及降级说明，不制造题目。状态成功不等于业务通过。
|
||
|
||
`evidence_ids` 保存进入该判断的授权证据范围；它不证明模型真的使用或正确理解了证据。新增引用需再校验，主审仍逐项检查是否支持意见。
|
||
|
||
`NativeMetric`：`name:string`、`value:number`（有限值）、`semantics:string`（非空）、`source:provider_native/self_reported`。`native_metrics` 可为空；范围校验根据版本化适配规范，禁止把缺失值填0或1。它只用于审计/独立评测，不成为通用置信阈值或审批概率。
|
||
|
||
Jev 专有 Choice/Score/Noul 等响应只在适配器内部处理，具体厂商 schema 在真实接入前依据官方版本确认。若某题由原生连续输出转为 binary，须有该模型/题型独立验证过的映射和拒答区间；未验证就不声明 binary 能力，不默认套用0.5阈值。原始供应商指标仅保留原语义，不为 local 捏造同名概率。
|
||
|
||
本地模型可返回 choice/score/binary/unknown；没有原生概率就返回空指标。模型自己写的“置信度90%”即使记录也只能标 self_reported，不作为已校准概率。两类模型的原生指标都不能改写 ScreeningRun.probability；P0 仍为 null。
|
||
|
||
## 6. 失败边界与回滚
|
||
|
||
配置拒绝 E-13 发生在创建运行之前；运行中能力不支持 E-14、输出非法 E-15、调用故障 E-06、外发禁止 E-10、预算耗尽 E-08 均有可见记录。相关题目未完成时保留其他结果；关键依据缺失则依主审完整性规则给补件/信息不足，不能默认推进。
|
||
|
||
默认配置切回旧修订只影响未来新运行；持久化的运行配置与判断字段通过追加迁移引入。DDL 在 M1 定案，不覆盖旧对象或当前生产库。外部模型权重、密钥、原始材料不作为 Git 备份内容。
|
||
|
||
## 7. 验收与交付范围
|
||
|
||
AC-17：同题/同证据，两适配器输出可被同一主审契约消费；local 在无 Jev Key 的环境实际运行，调用记录无 Jev 请求。
|
||
AC-18：畸形值拒绝；指标保留原语义；local 自评分不成为审批概率；无证据与合理拒答返回 unknown。
|
||
AC-19：配置权限、禁用状态、能力缺失和出口撤销均有反例测试；不外发未批准材料。
|
||
AC-20：排队后切换默认不会改变该运行；重试不改提供方，幂等重放不改配置。
|
||
AC-21：两种服务均不可用时仍可关闭专项模块运行主审，结果明确限制。
|
||
|
||
业务效果验收使用同一冻结样本集和专家标准，分别统计两种模式的漏检、误报、无依据结论、拒答率、时延和成本。契约兼容不代表模型能力等价；验收合格才能将对应配置标为 ready。Jev 没有 Key 时其 live 测试标未验证，不阻塞已经通过验证的 local 模式。
|
||
|
||
本地具体模型、硬件和服务协议仍属于 OQ-03/04，接入前选择并验证；没有真实历史数据时只报告演示和合成用例结果。当前交付仅为设计，后续按 M3 落代码、测试与配置模板。
|