Decision Model Providers — Per-Feature Switch and Local Replay
Lets each rental AI feature (listing, chat, duplicate) choose its own System One decision model, TypeSafe Jev or the self-hosted open-weight Kev, through one Provider interface, a registry and per-provider threshold tables. Before any switch, real production calls are replayed against Kev on the developer's own machine through a loopback-only client, and a per-unit report compares the two models. Updated after the duplicate check shipped (#146) to adapt its judge, sweep gate, threshold and eval tool.
摘要
目前每个 Jev 功能都锁定在一个写死的模型上。本设计让每个租房功能通过一个接口、一个注册表和按提供方划分的阈值表, 自行选择决策模型 —— TypeSafe Jev 或自托管的 Kev。在任何切换之前,会先在开发者自己的机器上用 Kev 重放真实的生产调用, 并由报告对比两者。
相关:Jev 房源检查(共享客户端、J13 命名);Jev 聊天消息检查;Jev 重复检查; ADR-0068(重放隐私);ADR-0064、ADR-0066、ADR-0067;Kev:github.com/jaredpalmer/kev。
为什么
共享客户端把 "model": "jev-latest" 发送到 https://api.typesafe.ai,而且是写死的。
现在已有其他决策模型。Kev 是一族开放权重模型,完全照搬了 TypeSafe 的 System One API。
POST /v1/systemone,请求和回答 JSON 相同- Noul、Choice、Score 问题
- 返回概率
- 由我们自己托管(GPU)
- 概率的校准方式不同
- 答案排序能力较弱:在 5% 错误预算下自动化 45–57%,Jev 为 70%
我们希望:
- 每个功能自选提供方:房源、聊天、重复。
- 先对比再切换:在本地 GPU 机器上用 Kev 重放真实生产调用,然后再决定。
- 以后方便加提供方:一个接口。只有当出现 API 不同的提供方时,才编写新的适配器。
交付物
| # | 交付物 |
|---|---|
| 1 | 共享 typesafe 包中的 Provider 接口 |
| 2 | 客户端 WithModel 选项;模型名不再写死 |
| 3 | 启动时根据配置构建的提供方注册表(jev、kev) |
| 4 | 按功能划分的提供方环境变量 |
| 5 | 每个判定器内按提供方划分的阈值表;启动时拒绝未经测试的组合 |
| 6 | cmd/replay-typesafe:本地重放生产调用并出报告,另附一个仅限回环地址的共享 HTTP 客户端(F1),供重放和真实数据评估使用 |
| 7 | cmd/eval-listing-check、cmd/eval-message-check 和 cmd/eval-duplicate-check 上的 --base-url 与 --model 参数;cmd/eval-message-check 中的 --threshold 评分;cmd/eval-duplicate-check 中的 --threshold 覆盖(U3) |
| 8 | ADR-0068 |
决策
| # | 决策 |
|---|---|
| P1 | 所有功能的生产默认值仍为 jev。 |
| P2 | 通过环境变量和重新部署来切换。只有切换变得频繁时,才会以后加管理页面。 |
| P3 | 每个功能有自己的提供方环境变量(TYPESAFE_LISTING_PROVIDER、TYPESAFE_CHAT_PROVIDER、TYPESAFE_DUPLICATE_PROVIDER)。 |
| P4 | 阈值写在代码里,每个判定器一张表,按提供方名称索引。每个条目保持现在的形状:一个共享 Noul 阈值,以及(房源)一个共享 Score 阈值。新条目必须先有评估或重放结果。按问题的阈值只能在以后有证据的 PR 中加入(Q8)。 |
| P5 | 当功能开关打开,而其提供方未注册(包括缺少 Jev 密钥)或没有阈值条目时,服务器拒绝启动。现在缺少密钥会静默关闭该功能(Q6)。 |
| P6 | 通过在本地机器上重放来对比,而非线上影子调用。生产环境只调用其选定的提供方。 |
| P7 | 重放工具使用开发者的普通数据库登录读取生产数据。只执行 SELECT。不设只读角色。 |
| P8 | 重放输出只保存在本地文件中。不写回生产环境。只有当别人也需要结果时,才会以后加 typesafe_replays 表。 |
| P9 | 目前共享接口是唯一的抽象。只有选定了 API 不同的提供方时,才编写第二个适配器。 |
| P10 | 调用日志仍在 HTTP 客户端内部。Jev 和 Kev 共用该客户端,因此两者都会被记录。第二个适配器出现时,日志再移到包装层。 |
| P11 | 包名保持 typesafe。"System One" 是 TypeSafe 定义、Kev 照搬的 API 形状。 |
| P12 | 注册表列表写在代码里。环境变量只存 URL 和密钥。新提供方反正需要阈值表,而那是代码改动。 |
| P13 | Kev 生产启用规则(Q7):Kev 的第一个阈值条目必须同时在代码中固定一个不可变模型 id,并附上重放证据。改变权重或 id 需要重新评估并复审阈值。kev-latest 仅用于本地评估。Jev 保持 jev-latest。 |
质询决策(2026-09-26)
| # | 决策 | 原因 | 位置 |
|---|---|---|---|
| Q1 | 只有判定器存在时房源检查才算开启。删除环境变量读取和 SetRentalJevEnabledFunc。定时扫描加 nil 保护。 | 两个事实来源可能不一致,并调用 nil 判定器 | §5.4 |
| Q2 | 重放选择 model LIKE 'jev-%',可选 --jev-model,按版本计数 | 日志存的是返回的模型(jev-1.13.0),不是 jev-latest | §5.6、§5.7 |
| Q3 | 一个单元 = 每个 ref_id 最新的 200 行,平局用 id DESC 决定,去重后再应用 --limit | 重试和表单检查会让每个单元产生多行日志 | §5.6、§5.7 |
| Q4 | run.json 冻结时间窗口、过滤条件、目标和单元列表。不含密钥。重跑时拒绝冲突的参数。 | 新行和不断移动的 --since 会改变续跑的结果 | §5.6 |
| Q5 | 本地 labels.jsonl,人工标注优先,A/B 两部分分开,--report-only,不宣称召回率 | 管理员只看得到 Jev 发现的问题。缺少标注不等于负例。 | §5.7 |
| Q6 | 开关打开 + 提供方未就绪 = 启动错误,包括缺少 Jev 密钥 | 静默关闭会掩盖丢失的密钥和错误的提供方名称 | §5.4、§8 |
| Q7 | Kev 在第一个阈值之前需要固定的不可变模型 id。kev-latest 仅限本地。 | 同一名称下更换权重会让调好的阈值漂移 | §5.3、P13 |
| Q8 | 每个判定器每个提供方一个共享 Noul/Score 阈值。按单元扫描。 | 标注是按消息的,而表里放不下按问题的数值 | §5.5、§5.7 |
| Q9 | 消息评估在 --threshold 下对照 ExpectedFindings 评分。房源评估只做描述。使用 --base-url 时必须给 --model。 | 只有消息用例有正确答案。避免把 jev-latest 发给 Kev。 | §5.8 |
| F1 | 重放目标仅限回环地址:参数检查、拨号检查、不跟随重定向、不走代理、不可覆盖 | ADR-0068 只允许开发者自己的机器 | §5.6 |
| F2 | 评估使用 db 或文件数据源并指定自定义 --base-url 时,使用同样的保护 | 这些数据源可能包含真实数据 | §5.8 |
| F3 | 注入的假判定器只跳过它自己功能的查找 | 测试在没有注册表的情况下注入假对象 | §5.4 |
| F4 | 重放每次调用超时,默认 60 秒,记录下来,可续跑 | http.Client{} 没有超时 | §5.6 |
重复检查已上线(2026-09-26,#146)
重复检查在本改动之前就已实现。它沿用旧模式,所以由本改动来适配。已上线的内容:
| 内容 | 位置 |
|---|---|
| 只要有客户端或密钥就构建判定器,不读开关 | rental/module.go:348-355 |
定时扫描每次都读取全局配置(config.Get()),另有一个 SetEnabledFunc 测试钩子 | usecase/duplicate_check_sweep.go:54-65,110 |
IsRentalDuplicateEnabled() = 密钥 && 租房开关 && 重复开关 | config.go:61-63 |
DuplicateHintThreshold = 0.7 定义了两次。定时扫描用它自己的副本,评估工具用适配器的。 | duplicate_judge.go:14、duplicate_check_sweep.go:19,222 |
| 端口返回原始概率。定时扫描负责按阈值判断,并把 p 存到提示上。 | port/ports.go:1221 |
评估工具已按阈值对照 ExpectedDuplicate 评分 | cmd/eval-duplicate-check/main.go:220 |
| 记录的状态按位置列出地址,不含 id。提示没有调用 id。 | duplicate_judge.go:44-54、rental_duplicate_hints |
| # | 决定 | 原因 | 位置 |
|---|---|---|---|
| U1 | 只有判定器存在时重复检查才开启,与房源相同(Q1)。删除定时扫描的 isEnabled、它的 config.Get() 读取和 SetEnabledFunc。只有开关打开且提供方解析成功时才构建判定器。 | 又出现两个事实来源。读取全局配置违反"配置之外不读 TYPESAFE_*"。 | §5.4 |
| U2 | 适配器中的阈值表 {"jev": 0.7}。NewDuplicateJudge(p, name) 在缺少条目时报错。端口新增 Threshold() float64。定时扫描使用它,并删除自己的常量。 | 两份 0.7 可能不一致。定时扫描需要原始 p 写入提示行,所以判定器不能隐藏 p。 | §5.5 |
| U3 | cmd/eval-duplicate-check 新增 --base-url 和 --model(也有 F2 保护),以及 --threshold。默认是 jev 条目。设置 --base-url 时必填。 | 不能悄悄用 Jev 的数值给 Kev 评分 | §5.8 |
| U4 | 重放支持 duplicate_check。一个单元 = 一次主体调用。发现 = 任一候选 >= 阈值。一致性合并所有候选问题计算。没有标注。 | 日志不含候选 id,提示没有调用 id,所以提示无法对应到某个重放答案 | §5.6、§5.7 |
| U5 | ADR-0068 也覆盖 cmd/eval-duplicate-check | 三个评估工具使用同一条真实数据规则 | ADR-0068 |
| 被否决的方案 | 否决原因 |
|---|---|
| 把阈值传入定时扫描的构造函数(U2) | 那样模块和判定器必须约定同一个数值。判定器本来就知道自己的提供方。 |
| 端口返回命中标志而不是 p(U2) | 提示行保存 p,管理员能看到它。 |
现在就给 rental_duplicate_hints 加 call_id 以支持重放标注(U4) | 为一份还没人运行过的报告改数据库结构。需要重复检查标注时再加。 |
| 按地址把提示匹配到重放的候选(U4) | 调用之后地址可能改变。错误的关联会导致错误的评分。 |
假设
| # | 假设 | 如果不成立 |
|---|---|---|
| A1 | Kev 返回的模型名永远不会以 jev- 开头。 | Kev 的行会进入重放。需收紧过滤条件。 |
| A2 | model 为 NULL 的 200 行不是可用的 Jev 行。LIKE 会丢弃它。 | 这类行被静默跳过,报告计数中也看不到。 |
| A3 | 管理员的 reviewed 表示问题属实。false_alarm 表示不属实(admin_message.go:84)。 | A 部分的精确率会出错。需重新审视标注映射。 |
| A4 | typesafe_calls 保留 90 天(保留任务)。 | 默认窗口和保留期丢失计数会改变。 |
| A5 | 在任何重放或真实数据评估之前,Gremlin 确认允许使用真实数据(ADR-0066/0067/0068)。 | 不要运行重放。 |
| A6 | 部署前在本仓库之外检查生产和 UAT 的密钥(§8 第 1 步)。 | 开启开关的功能会导致无法启动。 |
被否决的方案
| 方案 | 否决原因 |
|---|---|
| 生产环境中的线上影子调用 | 调用量翻倍,且需要托管 Kev。本地 GPU 上的重放能回答同样的问题。 |
| 备用链(Jev 挂了 → Kev) | 不是目标。在一个功能中混用两个模型的概率会破坏阈值。 |
| 一个全局模型开关 | 各功能必须分别选择(P3)。 |
| 现在就为每个提供方写适配器 | Kev 使用相同的 API。第二个适配器只会复制客户端。 |
| 阈值放在环境变量中 | 多出约 10 个环境变量,而且容易设置未经测试的数值。 |
注册表条目上的 kind 字段 | 目前它只会有一个值。等第二个适配器时再加。 |
| 重放使用只读数据库角色 | 负责人为简单起见否决(P7)。 |
isRentalJevEnabled() 继续读取环境变量(Q1) | 第二个事实来源。它可能与注册表不一致,并在 nil 判定器上 panic。 |
typesafe_calls 上加 provider 列(Q2) | 返回的模型名已经能区分 Jev 和 Kev。 |
按 ref_id 续跑,不冻结窗口(Q4) | 窗口和最新行在两次运行之间仍会变化。 |
| 缺少 Jev 密钥时继续静默关闭(Q6) | 会掩盖丢失的密钥。所有提供方用一条规则更简单。 |
| 现在就选定 Kev 版本(Q7) | 还没有证据。固定版本应与第一个阈值一起做。 |
| 现在就用按问题的阈值(Q8) | 标注是按消息的。没有证据表明某个问题需要单独的数值。 |
| 为房源评估评分(Q9) | 其用例没有正确答案。编写答案是新的标注工作。 |
| 非回环重放目标的覆盖参数(F1) | 违反 ADR-0068。SSH 隧道可以覆盖局域网 GPU 的情况。 |
范围
包含:共享接口、客户端模型选项、注册表、按功能的配置、阈值表、 启动检查、重放工具、评估工具参数、ADR-0068。
不包含:见 不在范围内。
接口与客户端
位于 internal/shared/infrastructure/typesafe:
// Provider answers System One questions (noul, choice, score) about a state.
// *Client implements it for every provider that speaks the System One API.
type Provider interface {
Judge(ctx context.Context, caller Caller, state any,
questions map[string]Question) (*Result, error)
}
它与租房模块当前的 rentaltypesafe.Client 接口签名相同(listing_judge.go:20)。
租房模块删除自己的接口,改用 sharedtypesafe.Provider。由于方法未变,测试假对象继续可用。
客户端改动
- 新选项
WithModel(name string)。DefaultModel = "jev-latest"仍是默认值。 judgeRequest.Model使用c.model,而不是常量。WithBaseURL已存在。生产环境现在为kev设置它。- 空 API 密钥不发送
Authorization头。本地 Kev 可以不设密钥运行。 - 日志不变(P10)。
typesafe_calls.model列已记录服务器返回的模型名。
注册表
type ProviderSpec struct {
Name string // "jev", "kev"
BaseURL string
APIKey string
Model string
}
// BuildProviders returns one *Client per spec that is configured.
func BuildProviders(specs []ProviderSpec, opts ...Option) map[string]Provider
列表在 cmd/server/main.go 中根据配置构建。所有客户端共用调用日志仓库和日志器选项。
| 名称 | 何时注册 | BaseURL | 密钥 | 模型 |
|---|---|---|---|---|
jev | 设置了 TYPESAFE_API_KEY | https://api.typesafe.ai | TYPESAFE_API_KEY | jev-latest |
kev | 设置了 KEV_BASE_URL | KEV_BASE_URL | KEV_API_KEY(可选) | KevModel 常量。现在是 kev-latest;在第一个阈值之前固定(P13)。 |
模型固定(Q7)
Kev 的第一个阈值上线时,要在 KevModel 中固定一个不可变模型 id,并附上重放报告。
阈值是根据某个模型的数值调出来的。kev-latest 让运行 Kev 服务器的人可以在同一名称下更换权重,
调好的阈值会悄悄漂移。
否决:现在就选定 Kev 版本 —— 还没有证据。
- 今天不选定 Kev 版本。
KevModel = "kev-latest",且没有kev阈值条目,所以 P5 已阻止 Kev 在生产中运行。 - 添加 Kev 第一个阈值的 PR 同时把
KevModel设为不可变 id,并附上重放报告。 - 如果任何判定器有
kev阈值条目而KevModel以-latest结尾,单元测试会失败。 - 本地重放和评估工具传入
--model,所以kev-latest在那里仍可使用。 - Jev 保持
jev-latest,以维持现有行为。Jev 返回的版本可能不经通知就变化,而阈值由我们自己负责复审。重放报告会记录看到的 Jev 版本。托管的 Kev 制品如何保持不可变,由托管 ADR 决定。
app.Container.TypeSafeClient *typesafe.Client 改为 DecisionProviders map[string]typesafe.Provider。
移除 rental/module.go 中的 newTypeSafeClient。模块按名称查找提供方。
配置
TypeSafeConfig 新增:
KevBaseURLKEV_BASE_URL,默认""KevAPIKeyKEV_API_KEY,默认""ListingProviderTYPESAFE_LISTING_PROVIDER,默认jevChatProviderTYPESAFE_CHAT_PROVIDER,默认jevDuplicateProviderTYPESAFE_DUPLICATE_PROVIDER,默认jev
开关保留(TYPESAFE_RENTAL_ENABLED、TYPESAFE_RENTAL_CHAT_ENABLED、
TYPESAFE_RENTAL_DUPLICATE_ENABLED)。"开启"的含义改变(Q6):
| 情况 | 现在 | 之后 |
|---|---|---|
| 开关关闭 | 功能关闭 | 功能关闭。不查找提供方或阈值。 |
| 开关打开,提供方已注册,阈值条目存在 | 功能开启 | 功能开启 |
开关打开,TYPESAFE_API_KEY 为空,提供方 jev | 静默关闭(config.go:49-63) | 启动错误 |
开关打开,提供方 kev,没有 KEV_BASE_URL | 不适用 | 启动错误 |
| 开关打开,提供方没有阈值条目 | 不适用 | 启动错误 |
- 开关与就绪状态分开。
IsRentalEnabled()、IsRentalChatEnabled()和IsRentalDuplicateEnabled()只反映开关,不再查看密钥。 - 启动时,对每个开启的功能,模块从注册表解析所选提供方,并查找该名称的阈值条目。两者都必须成功。
- 只有这样才会构建并注入判定器。任何失败都会返回一个指明功能和提供方的错误,服务器不会启动。
- 聊天仍需要租房开关和聊天开关都打开,与现在一样。重复检查仍需要租房开关和重复开关都打开。
- 通过模块选项注入的假判定器(
o.listingJudge、o.messageJudge、o.duplicateJudge)只为它自己的功能跳过提供方和阈值查找(F3)。其他功能仍执行启动检查。
房源"开启" = 房源判定器存在(Q1)
现在模块总是构建房源判定器,而 isRentalJevEnabled()
(listing_check_queue.go:20-43)直接读取环境变量。改动之后:
- 只有开关打开且提供方和阈值都解析成功时,模块才构建房源判定器。开关关闭:判定器为
nil,与聊天相同。开关打开但未就绪:启动错误,而不是nil(Q6)。 - 删除
isRentalJevEnabled()、它的环境变量读取,以及全局的SetRentalJevEnabledFunc。配置之外不再有代码读取TYPESAFE_*环境变量。 - 按用例的测试钩子(
SetJevEnabledFunc)只在测试仍需要时保留。大多数测试改为注入假判定器或nil。
| 路径 | 现在 | 之后 |
|---|---|---|
保存时入队(queueListingCheck,由 listing.go:332 调用) | 全局环境变量检查 | 当 uc.judge == nil 时跳过 |
表单检查(listing_check_form.go:43-78) | isRentalJevActive() && judge != nil | judge != nil |
定时扫描(listing_check_sweep.go:61-103) | isEnabled(),然后调用 judge 且无 nil 检查 | 当 judge == nil 时立即返回(nil 保护) |
重复检查"开启" = 重复判定器存在(U1)
与房源的规则相同:
| 路径 | 现在 | 之后 |
|---|---|---|
模块构建(module.go:348-355) | 只要有客户端或密钥就构建 | 只有 IsRentalDuplicateEnabled() 为 true 且提供方和阈值都解析成功时才构建 |
定时扫描开关(duplicate_check_sweep.go:54-65,110) | config.Get() 读取开关,并且 judge != nil | 只看 judge != nil。删除 isEnabled、config 导入和 SetEnabledFunc。 |
入队(dup_check_due_at)现在不受开关控制,之后也保持不变。它没有成本。
阈值表
每个判定器持有一张按提供方名称索引的表。目前只有 jev 有条目:
var listingThresholds = map[string]ListingThresholds{
"jev": {Noul: 0.7, Score: 1.5},
}
var chatThresholds = map[string]float64{"jev": 0.7}
var duplicateThresholds = map[string]float64{"jev": 0.7}
-
listing / jev / Noulany Noul >= threshold→ 发现问题(6 个 Noul 问题) 0.7 -
listing / jev / Scoreaddr_completeness < threshold→ 发现问题;desc_quality仅为提示 1.5 -
chat / jev / Noulany asked Noul >= threshold→ 发现问题(3 个 Noul 问题) 0.7 -
duplicate / jev / Noulcandidate Noul >= threshold→ 提示(每个候选 1 个 Noul,最多 10 个) 0.7 -
kev暂无条目 需要重放 + 固定模型 —
- 构造函数接收提供方名称:
NewListingJudge(p Provider, name string) (*ListingJudge, error)。 - 缺少条目会返回错误。模块返回该错误,因此服务器拒绝启动(P5)。
- 此检查只在功能开启时运行。关闭的功能不构建判定器。这对房源是新行为(Q1)。聊天已经这样工作。
- 现有常量(
NoulThreshold、ScoreThreshold、ChatNoulThreshold、DuplicateHintThreshold)成为jev条目。引用它们的测试相应更新。
重复阈值由判定器持有(U2)
port.DuplicateJudge 新增 Threshold() float64。定时扫描比较 p >= uc.judge.Threshold()。
重复判定器为每个候选返回原始 p。定时扫描把 p 存到提示行上,所以它需要原始 p 和阈值。
目前 0.7 同时定义在 duplicate_judge.go:14 和 duplicate_check_sweep.go:19;删除定时扫描里的副本。
cmd/eval-duplicate-check 把 jev 条目作为默认阈值。
否决:把阈值传入定时扫描的构造函数;端口返回命中标志而不是 p。
重放工具 cmd/replay-typesafe
go run ./cmd/replay-typesafe --dsn "$PROD_DSN" --feature message_check \
--since 2026-09-01 --base-url http://127.0.0.1:8009 --model kev-latest --out ~/replay/
--dsn- Postgres DSN。必填。不回退到
.env。 --featurelisting_check、message_check或duplicate_check(U4)--since- 最早的
created_at。默认:90 天前。 --limit- 最多调用数。
0表示全部。 --jev-model- 可选。只取一个 Jev 版本,例如
jev-1.13.0。必须以jev-开头,否则工具退出。默认:所有 Jev 版本。 --base-url、--model、--api-key- 要重放的目标提供方。
--base-url必须是回环地址(F1)。 --timeout- 每次调用的期限。默认
60s(F4)。 --report-only- 跳过所有 Kev 调用。根据
answers.jsonl、labels.jsonl和最新的管理员标注重建report.md。 --out- 输出目录。必填。每次评估一个目录。如果其中已有
run.json,则续跑(Q4)。
流程
-
为每个单元选出最新的 Jev 调用(Q3)
一条消息或一个房源(
ref_id)就是一个单元,不论被检查过多少次。 -
解码
用
UnmarshalQuestion把input解码为state和questions。 -
重新发送
通过一个用
WithBaseURL和WithModel构建、且没有调用日志仓库的*Client发送。因此工具绝不会写入typesafe_calls。 -
记录
每次调用向
answers.jsonl追加一行:{call_id, ref_id, jev: <output>, kev: <answers>, error}。 -
续跑
重启时读取
run.json和answers.jsonl,然后只重放尚未回答的单元。 -
报告
加载标注,然后写出
report.md。
调用逐个执行。失败的调用会连同错误一起记录,本次运行中不重试。
SELECT * FROM (
SELECT DISTINCT ON (ref_id) id, ref_id, model, input, output, created_at
FROM typesafe_calls
WHERE app = 'rental' AND feature = $1
AND created_at >= $2 AND created_at < $5 -- $5 = frozen until
AND http_status = 200 AND model LIKE 'jev-%'
AND ($3 = '' OR model = $3) -- $3 = --jev-model
AND ref_id IS NOT NULL
ORDER BY ref_id, created_at DESC, id DESC
) latest
ORDER BY created_at, id
LIMIT NULLIF($4, 0) -- $4 = --limit, applied after dedupe
一条消息发送一次,如果第一次失败,会由定时扫描重试。每次尝试都会记录一行,ref_id 相同。
房源在每次表单检查和每次定时扫描检查时都会记录一行,且两次之间可能被编辑。
每次调用超时(F4)
客户端的 http.Client{} 没有超时(client.go:97)。判定器会加自己的期限,但重放没有。
因此每次重放调用都在 --timeout(默认 60 秒)下运行。超时会像其他失败一样记录为该单元的错误,
重跑时会再次处理该单元。
仅限回环地址的目标(F1,ADR-0068 要求)
真实的生产输入只能到达开发者自己机器上的模型。重放工具分三层强制执行:
-
参数检查
--base-url的主机必须是127.0.0.1、[::1]或localhost。其他任何值都会在查询数据库之前退出。 -
拨号检查
HTTP 传输层的拨号器检查实际连接的 IP(
net.Dialer的Control钩子)。非回环 IP 会让调用失败。因此修改localhost的 DNS 无法绕过参数检查。 -
不跟随重定向、不走代理
CheckRedirect返回错误,因为 Go 会在 307/308 时重新发送 POST 请求体。传输层的Proxy为nil,所以环境中的HTTPS_PROXY无法把调用转走。
冻结运行(Q4)
重放运行期间生产环境仍在记录日志。房源可能出现更新的行,于是它的"最新"调用会改变。--since 也每天变化。
所以第一次运行会把输入冻结在 --out/run.json 中:
feature、jev_model、limit- 来自参数
since- 来自
--since,或第一次运行时间减 90 天 until- 第一次运行的开始时间
base_url、model- 目标提供方
units- 选中的
{call_id, ref_id}列表,只有 id
- API 密钥绝不写入
run.json。 - 在同一个
--out中重跑时使用run.json,而不是当前时钟。任何与run.json不同的参数都会让工具退出,并报出字段名。 - 重跑只按
call_id获取未回答的单元。行已消失(被 90 天保留期清除)的单元计为保留期丢失,而不是错误。 - 即使部分完成的
answers.jsonl含有重复行,报告对每个ref_id最多只计一行。以该ref_id的第一行为准。 - 新的评估(新窗口或新目标)需要新的
--out目录。
标注与报告
| 功能 | 标注 | 单元 |
|---|---|---|
message_check | rental_messages.review_status:reviewed = 属实,false_alarm = 不属实;NULL = 未标注 | 按消息(ref_id = 消息 id)。任一 Noul 超过阈值,该消息即有发现。 |
duplicate_check | 无(U4) | 按主体房产(ref_id = 主体 id)。最新记录的定时扫描调用,以及该次调用的候选。任一候选超过阈值,该单元即有发现。只比较与 Jev 的一致性。 |
listing_check | 无 | 按房源(ref_id = 房源 id)。最新记录的快照 —— 不一定是管理员看到的内容,因为表单检查也会记录,而房源可能之后又被修改。只比较与 Jev 的一致性。 |
标注查询只对 id 列表执行 SELECT。
人工标注(Q5)
只有 Jev 发现问题的地方才有管理员标注。管理员消息列表只返回有发现的行
(admin_message_handler.go:26-50、admin_message.go:66-79)。所以只有 Kev 发现问题的消息
没有管理员标注,管理面板也无法显示它。
- 开发者通过 id 读取该消息,用其现有的生产数据库权限检查分歧(P7)。这与重放本身一样,需要 Gremlin 的确认(ADR-0068)。
- 开发者把结果写入
--out/labels.jsonl:{"ref_id": "...", "label": "real" | "not_real"}。只有 id。没有消息文本。 - 重放工具绝不打印或写出消息文本,分歧列表中也不会。
- 对同一个
ref_id,人工标注优先于管理员标注。 - 如果没做检查或不允许检查,该单元保持未标注。缺少标注绝不会被当作"不属实"。
报告内容
报告遵循判定器的真实形状(Q8)。每个判定器每个提供方只有一个共享 Noul 阈值和一个共享 Score
阈值(房源:6 个 Noul + 2 个 Score 问题;聊天:3 个 Noul;重复:每个候选 1 个 Noul,最多 10 个)。管理员标注是按消息的,不是按问题的。
report.md 对每个功能包含:
-
一致性,按问题
在 Jev 使用其阈值、Kev 使用相同数值时,Kev 和 Jev 在每个问题上给出相同答案的频率。这显示 Kev 在哪里不同。不对照标注评分。重复检查的问题键(
candidate_0…)是位置,不是固定问题,所以重复检查的一致性是合并所有候选问题得到的一个数字(U4)。 -
阈值扫描,按单元
一个共享 Kev Noul 阈值,从 0.50 到 0.90,步长 0.05。一个共享 Kev Score 阈值,从 0.5 到 2.5,步长 0.25。单元是否有发现按判定器的确切规则 —— 聊天:任一被问到的 Noul
>=阈值(message_judge.go:96-107);房源:任一 Noul>=阈值,或addr_completenessScore<阈值,而desc_quality低于阈值仅为提示(listing_judge.go:232-260);重复:任一候选 Noul>=阈值(duplicate_check_sweep.go:221-226)。每一步给出:与 Jev 的单元一致性,以及有标注时的单元级精确率。消息级标注绝不复制到其问题上。 -
分歧
Kev 有发现而 Jev 没有、以及反过来的调用 id 和 ref id。这是开发者的人工标注工作清单。
-
标注结果,分成两部分
A 部分(Jev 有发现):有管理员标注的单元 → 两个模型的精确率。B 部分(分歧):有人工标注的单元 → 两者不同时谁对。未标注的分歧只计数,不评分。
-
计数
符合条件的行(去重前)、没有
ref_id的行(被丢弃)、不同的单元数、已重放、失败、因保留期丢失、管理员已标注、人工已标注、未标注的分歧。单元也按 Jev 版本计数,这样窗口内的版本变化可以看到。
输出文件只包含 id、概率和运行设置。不写入状态文本,也不写入 API 密钥。
评估工具参数
cmd/eval-listing-check、cmd/eval-message-check 和 cmd/eval-duplicate-check 新增 --base-url 和 --model。
- 设置
--base-url时,API 密钥可选,--model必填。否则工具会把jev-latest发给 Kev。缺少--model会报错退出。 - 不设置
--base-url时,两个参数保持现有行为(TypeSafe、jev-latest)。 - 真实数据留在本地(F2)。只有内置的
--source synthetic算安全。--source db和任何文件路径都视为可能是真实数据。这类数据源加上自定义--base-url时,工具使用仅限回环的客户端(参数检查、拨号检查、不跟随重定向、不走代理)。合成用例可以发往任何 URL。
目前房源和消息评估工具只打印概率。重复评估工具已经评分(Q9、U3):
eval-duplicate-check
评分,与现在相同
- 有正确答案:
ExpectedDuplicate(cases.go:34),已按DuplicateHintThreshold评分(main.go:220)。 - 新的
--threshold参数。默认是jev表条目。 - 设置
--base-url时必填,这样 Kev 不会在没说明的情况下用 Jev 的数值评分。
eval-message-check
评分
- 有正确答案:
ExpectedFindings(cases.go:29),目前只被--dry-run使用(main.go:170)。 - 新的
--threshold参数,评分时必填,无默认值。 - 发现代码 = 被问到的 Noul
>=阈值(Q8 规则)。 - 发现代码与
ExpectedFindings作为集合相等时即精确匹配。 - 报告:精确匹配数,以及每个用例遗漏和多出的代码。
eval-listing-check
仅描述
EvalCase没有期望字段(cases.go:21-29)。- 像现在一样打印概率。
- 不评分,因为用例没有标注。
合成消息集和合成重复集是仅有的有已知负例的数据。重放没有负例(Q5),所以评估工具和重放回答的是不同的问题。
重复检查
重复检查先上线了(#146)。本改动负责适配它(见重复检查已上线):
- 判定器接收一个
Provider和一个提供方名称。它通过配置读取TYPESAFE_DUPLICATE_PROVIDER。 - 开启 = 判定器存在。删除定时扫描的全局配置读取(U1)。
- 它的 0.7 阈值成为表中的
jev条目,通过Threshold()取得(U2)。 - 评估工具获得提供方参数和阈值覆盖(U3)。
- 重放支持它,但没有标注(U4)。
边界情况
| 情况 | 行为 |
|---|---|
功能开启,提供方未注册(例如 kev 但没有 KEV_BASE_URL) | 启动错误,指明功能和提供方 |
功能开启,提供方 jev,TYPESAFE_API_KEY 为空 | 启动错误。现在是静默关闭。 |
| 功能开启,提供方没有阈值条目 | 启动错误 |
| 功能关闭,提供方值无效 | 忽略。不构建判定器。 |
| 环境变量中是未知的提供方名称 | 如果该功能开启,则启动错误 |
| 重放期间 Kev 服务器宕机 | 每次调用记录错误。重跑时续跑。 |
重跑时参数与 run.json 不同 | 工具退出并指明字段。不重放任何内容。 |
| 两次运行之间记录了新行 | 看不到。查询冻结在 until。 |
| 单元的行在两次运行之间被清除 | 计为保留期丢失 |
部分完成的 answers.jsonl 对一个 ref_id 有两行 | 报告保留第一行 |
重放的 --base-url 不是回环地址 | 工具在任何数据库查询前退出 |
localhost 解析为非回环 IP | 拨号失败。记录为该单元的错误。 |
| Kev 服务器返回重定向 | 调用失败。不跟随。 |
shell 中设置了 HTTPS_PROXY | 受保护的客户端会忽略它 |
评估使用 --source db 或文件,并指定非回环 --base-url | 工具退出 |
| Kev 调用卡住 | 在 --timeout(60 秒)时失败。重跑时重试。 |
| 测试注入假房源判定器,聊天开关打开但没有提供方 | 跳过房源查找。聊天仍会导致启动失败。 |
| 只有 Kev 有发现,且未做检查 | 未标注。只计数,绝不作为"不属实"评分。 |
| 人工标注与管理员标注不同 | 人工标注优先 |
typesafe_calls 中超过 90 天的行 | 已被清除。无法重放。 |
input 行解码失败 | 记录为错误行。运行继续。 |
| 窗口内 Jev 版本发生变化 | 默认重放所有版本。报告按版本计数。--jev-model 可选其一。 |
--jev-model 不以 jev- 开头 | 工具在任何查询前退出 |
同一个 ref_id 被记录多次 | 最新的 200 行胜出。created_at 相同时用 id DESC 决定。 |
没有 ref_id 的行 | 不重放。计入报告。 |
| Choice 选项顺序 | Go 按排序顺序序列化 map 键,所以两个提供方看到的顺序相同 |
| 重复开关打开,定时扫描的判定器为 nil | 不会发生:开关打开但提供方未就绪是启动错误。开关关闭:判定器为 nil,定时扫描立即返回。 |
重复判定器用 Kev 但没有 kev 条目 | 启动错误,与其他判定器相同 |
| 重复重放,主体在地址修改后被重新检查 | 每个主体取最新一次调用,以及该次调用的候选 |
重复评估设置了 --base-url 但没有 --threshold | 工具退出 |
测试
租房模块的 Go 测试使用 -p 1 运行。
| 区域 | 测试 |
|---|---|
| 客户端 | WithModel 在请求体中发送该模型。默认是 jev-latest。空密钥不发送 Authorization 头。 |
| 注册表 | 当 KevModel 以 -latest 结尾时存在 kev 阈值条目,测试失败(P13)。jev 只在有密钥时注册。kev 只在有 URL 时注册。缺少的规格不在 map 中。 |
| 配置 | 提供方环境变量默认为 jev。IsRentalEnabled() / IsRentalChatEnabled() 只跟随开关,与是否有密钥无关。 |
| 判定器 | 按提供方查找阈值。缺少条目会让构造函数失败。现有判定器测试在 jev 上通过。 |
| 模块 | 注入的假判定器只跳过自己功能的查找;另一个开启但没有提供方的功能仍会报错。功能开启但提供方未注册或未测试 → 错误。开关打开、使用 jev 且 TYPESAFE_API_KEY 为空 → 指明功能的启动错误(缺少密钥测试)。功能关闭 → 无错误、无判定器。 |
| 房源开启状态 | nil 判定器:保存时不入队,表单检查返回 checked: false,定时扫描直接返回、不认领行。没有测试使用 SetRentalJevEnabledFunc(已删除)。 |
| 重复开启状态 | 开关关闭 → 不构建判定器。nil 判定器 → 定时扫描不查询。定时扫描不读配置。没有测试使用定时扫描的 SetEnabledFunc(已删除)。扫描命中遵循 Threshold():阈值为 0.8 的假判定器让 0.75 的候选不命中。 |
| 目标保护 | 参数检查拒绝 http://10.0.0.5、https://api.typesafe.ai,接受 127.0.0.1、[::1]、localhost。即使 URL 主机被允许,拨号检查也会让连接非回环 IP 失败(假解析器)。httptest 服务器返回的 307 不会被跟随,重定向目标收不到请求。不使用 HTTPS_PROXY。 |
| 重放 | 每次调用超时:睡眠超过 --timeout 的处理器被记录为错误,下次运行会重试。针对 httptest 假服务器做解码 → 重发的往返测试。续跑跳过已完成的 id。客户端没有日志仓库。在固定的答案文件上验证报告扫描计算:单元是否有发现遵循各判定器规则(聊天只看被问到的 Noul;房源 desc_quality 永远不产生发现);标注永不按问题拆分。坏的输入行被记录,不致命。选择保留 jev-1.13.0 行,丢弃 kev-* 行。--jev-model 缩小到一个版本,并拒绝非 jev- 值。报告按版本计数。去重为每个 ref_id 保留一个最新行,使用 id 决胜;null ref_id 只计数不重放;--limit 计的是单元而不是行。重跑使用 run.json 的窗口,拒绝冲突参数,只获取未回答单元,把被清除的单元计为保留期丢失。run.json 不含 API 密钥。报告每个 ref_id 只保留一行。重复检查:单元发现 = 任一候选 >= 阈值,一致性合并计算,不查询标注,报告标明未标注。人工标注优先于管理员标注;缺少标注绝不作为负例评分;A、B 两部分分开;--report-only 不调用 Kev;没有输出文件包含消息文本。 |
| 评估参数 | 真实数据源(db 或文件)加非回环 --base-url 会退出;合成数据用同一 URL 可运行。--base-url 和 --model 传到客户端。设置 --base-url 时密钥可选。--base-url 没有 --model 会退出(所有工具都是)。消息评估评分:集合精确匹配,每个用例的遗漏和多出代码,只统计被问到的问题,--threshold 必填。房源评估不打印分数。重复评估:默认阈值是 jev 条目;--threshold 改变判定线;设置 --base-url 而没有 --threshold 会退出。 |
上线步骤
-
以
jev上线所有功能都用
jev。一个行为变化:开关(TYPESAFE_RENTAL_ENABLED、TYPESAFE_RENTAL_CHAT_ENABLED、TYPESAFE_RENTAL_DUPLICATE_ENABLED)打开而TYPESAFE_API_KEY为空时,现在会阻止启动。运维人员需先检查每个环境的密钥;本仓库不含密钥,所以无法在此完成。 -
本地 Kev 评估
在本地运行 Kev。用
--base-url和--model运行评估工具。在 Gremlin 确认后(ADR-0068),用回环--base-url对生产数据运行重放。 -
固定 + 阈值
如果 Kev 在某个功能上胜出:在一个 PR 中把
KevModel固定为不可变 id,添加阈值条目,并把重放数据(包括看到的 Jev 版本)写进 PR 描述(P13)。之后任何权重或 id 的变化都要重复这一步。 -
托管 ADR
为生产托管 Kev 是一个新的第三方,需要单独的 ADR。它还要说明固定的模型制品如何保持不可变。
-
切换
设置
KEV_BASE_URL和TYPESAFE_<FEATURE>_PROVIDER=kev,然后重新部署。
隐私 —— ADR-0068
每个 typesafe_calls 行都保存完整输入:房源地址和描述、聊天文本及最多 5 条之前的消息,
以及重复检查的房产地址(一个主体和最多 10 个来自其他房东的候选)。ADR-0068 允许重放工具从生产环境读取这些数据,并且只发送给开发者自己机器上的 Kev。
- 强制回环且不可覆盖;三个评估工具在非合成数据源加自定义
--base-url时都遵循同样规则。 - 输出文件只包含调用 id、ref id、概率和运行设置。不含状态文本,也不含 API 密钥。
- 只执行 SELECT;不向生产环境写入任何内容。开发者的数据库登录有写权限;为简单起见未采用只读角色。
- 人工标注:用现有数据库权限按 id 读取单条消息;本地文件只存 id 和标注。
- 与 ADR-0066 和 ADR-0067 的校准一样,需要 Gremlin 确认。Gremlin 是责任方(同 ADR-0064)。
- 只能重放最近 90 天的调用。为生产托管 Kev 需要单独的 ADR。
不在范围内
- 切换提供方的管理页面(以后,如果切换变得频繁)。
- 线上影子调用。
- 在生产环境中保存重放结果。
- 第二个适配器,以及与之配套的日志包装层。
- 为生产托管 Kev。
- Kev 的阈值数值。它们来自第一次重放。
- 按问题的阈值。以后的 PR 可以凭重放证据加入。
- 提供方之间的备用切换。