English

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.

  • Predecessor Builds on the 2026-09-23 TypeSafe Jev listing check (shared client, J13 naming)
  • ADRs 0064 · 0066 · 0067
  • New ADR 0068
  • Status Approved

View source markdown ↗ generated by claude-opus-5-5 · diagrams mermaid

摘要

目前每个 Jev 功能都锁定在一个写死的模型上。本设计让每个租房功能通过一个接口、一个注册表和按提供方划分的阈值表, 自行选择决策模型 —— TypeSafe Jev 或自托管的 Kev。在任何切换之前,会先在开发者自己的机器上用 Kev 重放真实的生产调用, 并由报告对比两者。

  • 范围 backend/go
  • 提供方 jev(TypeSafe)和 kev(自托管,相同 API)
  • 功能 房源检查、聊天消息检查、重复检查
  • 默认 所有功能都用 jev(P1)
  • 切换方式 环境变量 + 重新部署(P2)
  • 对比方式 本地重放,而非线上影子调用(P6)
  • 隐私 仅限回环地址的重放 —— ADR-0068
  • 状态 已批准;质询于 2026-09-26 13:44 +08 结束(Q1–Q9、F1–F4);重复检查在 #146 上线后更新(U1–U5)

相关: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。

与 Jev 相同
  • POST /v1/systemone,请求和回答 JSON 相同
  • Noul、Choice、Score 问题
  • 返回概率
与 Jev 不同
  • 由我们自己托管(GPU)
  • 概率的校准方式不同
  • 答案排序能力较弱:在 5% 错误预算下自动化 45–57%,Jev 为 70%

我们希望:

  1. 每个功能自选提供方:房源、聊天、重复。
  2. 先对比再切换:在本地 GPU 机器上用 Kev 重放真实生产调用,然后再决定。
  3. 以后方便加提供方:一个接口。只有当出现 API 不同的提供方时,才编写新的适配器。

交付物

#交付物
1共享 typesafe 包中的 Provider 接口
2客户端 WithModel 选项;模型名不再写死
3启动时根据配置构建的提供方注册表(jev、kev)
4按功能划分的提供方环境变量
5每个判定器内按提供方划分的阈值表;启动时拒绝未经测试的组合
6cmd/replay-typesafe:本地重放生产调用并出报告,另附一个仅限回环地址的共享 HTTP 客户端(F1),供重放和真实数据评估使用
7cmd/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)
8ADR-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 和密钥。新提供方反正需要阈值表,而那是代码改动。
P13Kev 生产启用规则(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
Q4run.json 冻结时间窗口、过滤条件、目标和单元列表。不含密钥。重跑时拒绝冲突的参数。新行和不断移动的 --since 会改变续跑的结果§5.6
Q5本地 labels.jsonl,人工标注优先,A/B 两部分分开,--report-only,不宣称召回率管理员只看得到 Jev 发现的问题。缺少标注不等于负例。§5.7
Q6开关打开 + 提供方未就绪 = 启动错误,包括缺少 Jev 密钥静默关闭会掩盖丢失的密钥和错误的提供方名称§5.4、§8
Q7Kev 在第一个阈值之前需要固定的不可变模型 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
U3cmd/eval-duplicate-check 新增 --base-url 和 --model(也有 F2 保护),以及 --threshold。默认是 jev 条目。设置 --base-url 时必填。不能悄悄用 Jev 的数值给 Kev 评分§5.8
U4重放支持 duplicate_check。一个单元 = 一次主体调用。发现 = 任一候选 >= 阈值。一致性合并所有候选问题计算。没有标注。日志不含候选 id,提示没有调用 id,所以提示无法对应到某个重放答案§5.6、§5.7
U5ADR-0068 也覆盖 cmd/eval-duplicate-check三个评估工具使用同一条真实数据规则ADR-0068
被否决的方案否决原因
把阈值传入定时扫描的构造函数(U2)那样模块和判定器必须约定同一个数值。判定器本来就知道自己的提供方。
端口返回命中标志而不是 p(U2)提示行保存 p,管理员能看到它。
现在就给 rental_duplicate_hints 加 call_id 以支持重放标注(U4)为一份还没人运行过的报告改数据库结构。需要重复检查标注时再加。
按地址把提示匹配到重放的候选(U4)调用之后地址可能改变。错误的关联会导致错误的评分。

假设

#假设如果不成立
A1Kev 返回的模型名永远不会以 jev- 开头。Kev 的行会进入重放。需收紧过滤条件。
A2model 为 NULL 的 200 行不是可用的 Jev 行。LIKE 会丢弃它。这类行被静默跳过,报告计数中也看不到。
A3管理员的 reviewed 表示问题属实。false_alarm 表示不属实(admin_message.go:84)。A 部分的精确率会出错。需重新审视标注映射。
A4typesafe_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_KEYhttps://api.typesafe.aiTYPESAFE_API_KEYjev-latest
kev设置了 KEV_BASE_URLKEV_BASE_URLKEV_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 新增:

KevBaseURL
KEV_BASE_URL,默认 ""
KevAPIKey
KEV_API_KEY,默认 ""
ListingProvider
TYPESAFE_LISTING_PROVIDER,默认 jev
ChatProvider
TYPESAFE_CHAT_PROVIDER,默认 jev
DuplicateProvider
TYPESAFE_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 != niljudge != 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 / Noul any Noul >= threshold → 发现问题(6 个 Noul 问题) 0.7
  • listing / jev / Score addr_completeness < threshold → 发现问题;desc_quality 仅为提示 1.5
  • chat / jev / Noul any asked Noul >= threshold → 发现问题(3 个 Noul 问题) 0.7
  • duplicate / jev / Noul candidate 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。
--feature
listing_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)。
重放流程。生产数据只用 SELECT 读取;输入只会到达回环地址上的 Kev;输出是只含 id 和概率的本地文件。
重放流程。生产数据只用 SELECT 读取;输入只会到达回环地址上的 Kev;输出是只含 id 和概率的本地文件。

流程

  1. 为每个单元选出最新的 Jev 调用(Q3)

    一条消息或一个房源(ref_id)就是一个单元,不论被检查过多少次。

  2. 解码

    用 UnmarshalQuestion 把 input 解码为 state 和 questions。

  3. 重新发送

    通过一个用 WithBaseURL 和 WithModel 构建、且没有调用日志仓库的 *Client 发送。因此工具绝不会写入 typesafe_calls。

  4. 记录

    每次调用向 answers.jsonl 追加一行:{call_id, ref_id, jev: <output>, kev: <answers>, error}。

  5. 续跑

    重启时读取 run.json 和 answers.jsonl,然后只重放尚未回答的单元。

  6. 报告

    加载标注,然后写出 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 要求)

真实的生产输入只能到达开发者自己机器上的模型。重放工具分三层强制执行:

  1. 参数检查

    --base-url 的主机必须是 127.0.0.1、[::1] 或 localhost。其他任何值都会在查询数据库之前退出。

  2. 拨号检查

    HTTP 传输层的拨号器检查实际连接的 IP(net.Dialer 的 Control 钩子)。非回环 IP 会让调用失败。因此修改 localhost 的 DNS 无法绕过参数检查。

  3. 不跟随重定向、不走代理

    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_checkrental_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 对每个功能包含:

  1. 一致性,按问题

    在 Jev 使用其阈值、Kev 使用相同数值时,Kev 和 Jev 在每个问题上给出相同答案的频率。这显示 Kev 在哪里不同。不对照标注评分。重复检查的问题键(candidate_0…)是位置,不是固定问题,所以重复检查的一致性是合并所有候选问题得到的一个数字(U4)。

  2. 阈值扫描,按单元

    一个共享 Kev Noul 阈值,从 0.50 到 0.90,步长 0.05。一个共享 Kev Score 阈值,从 0.5 到 2.5,步长 0.25。单元是否有发现按判定器的确切规则 —— 聊天:任一被问到的 Noul >= 阈值(message_judge.go:96-107);房源:任一 Noul >= 阈值,或 addr_completeness Score < 阈值,而 desc_quality 低于阈值仅为提示(listing_judge.go:232-260);重复:任一候选 Noul >= 阈值(duplicate_check_sweep.go:221-226)。每一步给出:与 Jev 的单元一致性,以及有标注时的单元级精确率。消息级标注绝不复制到其问题上。

  3. 分歧

    Kev 有发现而 Jev 没有、以及反过来的调用 id 和 ref id。这是开发者的人工标注工作清单。

  4. 标注结果,分成两部分

    A 部分(Jev 有发现):有管理员标注的单元 → 两个模型的精确率。B 部分(分歧):有人工标注的单元 → 两者不同时谁对。未标注的分歧只计数,不评分。

  5. 计数

    符合条件的行(去重前)、没有 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 会退出。

上线步骤

  1. 以 jev 上线

    所有功能都用 jev。一个行为变化:开关(TYPESAFE_RENTAL_ENABLED、TYPESAFE_RENTAL_CHAT_ENABLED、TYPESAFE_RENTAL_DUPLICATE_ENABLED)打开而 TYPESAFE_API_KEY 为空时,现在会阻止启动。运维人员需先检查每个环境的密钥;本仓库不含密钥,所以无法在此完成。

  2. 本地 Kev 评估

    在本地运行 Kev。用 --base-url 和 --model 运行评估工具。在 Gremlin 确认后(ADR-0068),用回环 --base-url 对生产数据运行重放。

  3. 固定 + 阈值

    如果 Kev 在某个功能上胜出:在一个 PR 中把 KevModel 固定为不可变 id,添加阈值条目,并把重放数据(包括看到的 Jev 版本)写进 PR 描述(P13)。之后任何权重或 id 的变化都要重复这一步。

  4. 托管 ADR

    为生产托管 Kev 是一个新的第三方,需要单独的 ADR。它还要说明固定的模型制品如何保持不可变。

  5. 切换

    设置 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 可以凭重放证据加入。
  • 提供方之间的备用切换。