金融SaaS单API密钥设计：结构化输出与幂等性实践

简短回答：只有当单一密钥、兼容 chat-completions 的网关能够保持严格的结构化输出验证、稳定的模型身份和重试元数据时，才应该选择它；对于金融科技支持分诊，这些控制措施比密钥保管库中凭证的数量更重要。

实际需求并不大：读取一条传入的支持工单，返回一个队列、紧急程度和原因。但运营风险不小。一条语法上有效的响应，仍然可能把信用卡争议工单发送到密码重置队列；而调度器重试可能从一张工单产生两次分配。一个 API 密钥让凭证管理更容易，但它无法解决这两种故障模式。

我曾因漏掉的作业和重复投递而被呼叫。那段经历改变了选择的标准。我需要一道边界，让 worker 在任何状态转换之前拒绝不良输出，同时我希望队列消费者将每次投递都视为可重复的。不变式很直白：模型响应在通过版本化 schema 和幂等提交之前是不受信任的输入。

SaaS 应用应该如何在一个 API 密钥背后比较兼容的 chat completions？

从回放测试开始，而不是功能矩阵。用同一份冻结的工单语料库喂养每个候选路径，保留原始响应，用生产中使用的相同解析器验证规范化结果。OpenAI、Anthropic 的 Claude 和 Google 的 Gemini 属于候选集，因为集成需求中提到了它们；它们的存在不能成为三个定制下游工作流的理由。应用应该看到一个内部 Decision 合约，并记录哪个模型产生了它。

比较的单位是一次被接受的决策，而不是 HTTP 成功。对于每个候选者，统计 schema 有效的响应、语义无效的分类、拒绝、超时、被限流的尝试，以及在提交时被抑制的重复工作。将这些类别分开统计。把它们合并成一个"成功率"会掩盖究竟是模型边界、运输层还是调度器需要关注。

使用一个小型的、经过裁定的语料库，代表支持团队实际运行的队列。一个有用的 fixture 包含工单 ID、脱敏文本、允许的目标队列、预期紧急程度，以及对模糊情况的注释说明。不要把模糊工单静默地强制为 gold label。给它们一个 manual_review 预期，然后测量提议的合约是否能表达它。我不确定任何静态语料库都能捕捉到新的欺诈模式；定期抽样审查生产中的分歧意见、由授权人员处理，才是解决这个缺口的方法。

因此，最简单的集成是具有最小已验证适配器的那一个，不一定是最短的快速上手代码片段。单一凭证的网关可以减少密钥分发并提供统一的请求形状。但问题是，chat 请求层的兼容性可能对 schema 强制、模型特定行为、取消、使用字段或重试语义一无所说。测试你的 runbook 依赖的那些字段。

事故的教训是关于提交，而不是调用

支持 worker 至少有三个独立失效的阶段：认领一个排队的工单、获取并验证分类结果、然后提交分配。在提交之前确认队列可能丢失工作。在提交之后确认队列，如果确认被中断，可能重新投递工作。这属于典型的至少一次处理领域，所以"调用模型一次"不是一个可用的正确性条件。

预防路径为每个逻辑分类赋予一个确定性操作键，衍生自工单 ID 和策略版本。它在一个事务中写入被接受的决策和一个出站事件，由该键上的唯一约束保护。重复的投递会读取现有结果而不是再次分配工单。这个设计也将推理尝试与业务效果分离：操作员可以重试一个临时调用，但只有一个经过验证的决策可以在提交中获胜。

策略版本属于键的一部分，因为在新路由规则下的刻意重新分类不是重复。模型标签不属于那里。如果切换候选模型改变了业务操作的身份，故障转移可能产生第二次分配。这正是那种看起来无害的细节——它通过了演示，却在夜间队列排空时把人叫醒。

调度增加了另一个边界。定时驱动的清理器重新发布租约过期的工单，必须使用与实时消费者相同的操作键。否则"恢复"路径就变成了具有不同去重规则的第二个写入者。将租约获取、推理尝试、验证结果、事务提交和确认记录为独立事件。然后告警可以区分不断增长的无主积压和模型合约拒绝峰值。

应用应该在副作用之前在哪里强制执行其 schema？

以下 Go 代码故意是一个应用边界，而不是 vendor 客户端。适配器可以将任何兼容的 chat 响应转换为字节；这个函数拥有生产所需的最严格规则。它拒绝额外字段、限制解释长度、检查受控词汇表，并对低置信度输出要求人工审查。调整该阈值是一个策略变更，应该被版本化，而不是在事故期间修补到 prompt 中。

package triage

import (
    "bytes"
    "encoding/json"
    "errors"
    "fmt"
    "io"
    "strings"
)

type Decision struct {
    TicketID  string  `json:"ticket_id"`
    Queue     string  `json:"queue"`
    Urgency   string  `json:"urgency"`
    Reason    string  `json:"reason"`
    Confidence float64 `json:"confidence"`
}

var allowedQueues = map[string]bool{
    "account_access": true,
    "card_dispute":   true,
    "manual_review":  true,
}

var allowedUrgency = map[string]bool{
    "standard": true,
    "urgent":   true,
}

func ParseDecision(raw []byte, expectedTicketID string) (Decision, error) {
    dec := json.NewDecoder(bytes.NewReader(raw))
    dec.DisallowUnknownFields()

    var d Decision
    if err := dec.Decode(&d); err != nil {
        return Decision{}, fmt.Errorf("decode decision: %w", err)
    }
    if err := dec.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
        return Decision{}, errors.New("decision must contain one JSON object")
    }
    if d.TicketID != expectedTicketID {
        return Decision{}, errors.New("ticket ID does not match claimed work")
    }
    if !allowedQueues[d.Queue] || !allowedUrgency[d.Urgency] {
        return Decision{}, errors.New("decision contains an unsupported enum value")
    }
    if d.Confidence < 0 || d.Confidence > 1 {
        return Decision{}, errors.New("confidence is outside the accepted range")
    }
    if d.Confidence < 0.80 && d.Queue != "manual_review" {
        return Decision{}, errors.New("low-confidence decision requires manual review")
    }
    if strings.TrimSpace(d.Reason) == "" || len(d.Reason) > 240 {
        return Decision{}, errors.New("reason is missing or too long")
    }
    return d, nil
}

这个解析器是必要的，但还不够。prompt 必须陈述相同的允许值，并且约束输出设施可以减少选定路径支持的情况下产生的格式错误响应。仍然要在本地验证。本地关卡是最终权威，因为它随业务规则一起迁移，并且可以在不调用网络的情况下执行。

默认情况下不要记录原始金融支持文本。存储一个脱敏的 fixture 标识符、如果策略允许的话存储内容哈希、策略版本、模型身份、尝试次数、验证类别和时间。保留的任何原始响应的访问需要与其他支持数据相同的审查。可观测性目标是回答"这张工单在哪里停下来的？"而不将遥测变成第二个客户数据存储。

调度、重试和发布需要一份 runbook

将适配器和策略作为独立变更部署。首先发布一个影子路径，读取正确处理的采样工单，但不写入任何分配。将它的规范化输出与活跃路径进行比较，让人类裁定分歧，只有在错误预算和隐私审查通过后才晋升。然后通过确定性切片（如工单 ID）进行金丝雀发布，这可以在发布期间保持重复投递使用相同策略。对于重试策略，按所有权对结果进行分类。格式错误或语义被拒绝的决策消耗了一次尝试，但不应当被提交；在有限次数的尝试后，将工单路由到人工审查。取消的请求只能在工单租约和操作截止时间仍然有效时重试。结果未知的提交必须通过读取操作键来解析，然后才能进行任何新的推理调用。按用户影响告警：最老的未分配工单年龄、超过分诊目标的工单数量、人工审查积压、以及被阻止的重复提交。请求延迟是诊断上下文。低中位数可能与滞留的长尾共存，而全局平均值可能掩盖某个在策略部署期间枚举值发生变化的队列。仪表板应该拆分传输失败、合约拒绝、审计发现的语义分歧和提交冲突。在告警期间，首先检查最老的工单，确认其租约，查询操作键，然后才决定是否进行另一次尝试；这个顺序防止仓促的回放变成第二次面向客户的分配。

Worker 不应该猜测。

批处理是一种单独的模式，而不是一种不可见的优化。OpenAI Batch API 指南描述了异步请求组，其完成窗口必须在工单目标内，同时保持每个工单相同的操作键。

紧急队列保持在即时路径上。

单一密钥方法什么时候是不合适的？

当应用依赖兼容层无法忠实暴露的原生能力时、当安全策略要求单独作用域的凭证和撤销域时、或者当事故响应需要每个 provider 的直接支持和遥测路径时，坚持使用直接的 vendor 集成。如果这些额外适配器和密钥保留了业务实际使用的控制措施，那就是合理的。

单一密钥网关也不适合当其模型身份无法被固定和审计时，或者当它无法返回足够多的元数据来区分限流和合约拒绝时。相反，当直接集成的差异渗透到整个应用时，它们是一笔糟糕的交易。把这些差异保持在适配器边界，让 worker 的其余部分依赖内部决策合约。

没有通用的赢家。OpenAI、Claude 和 Gemini 候选者应该通过相同的冻结 fixture 和失败分类法，访问模式被记录为测试变量而不是建议。一个凭证是一种便利。可回放的测试、严格的关卡和幂等提交才是生产设计。