🏠 总目录📚 本教程 17d · 企业助手服务层实战 ← →

智能体工程 · 17d

请求取消了,为什么草稿可能已经存在?

读完能做的判断:沿准入、扣额、搜索、草稿与重放解释状态,不把取消当撤销保证。

17d · 企业助手服务层实战

⏱ 阅读约 25 分钟 · 动手实践另计

本章保留教学代码、路径说明与历史验证结论;完整实验工程和运行记录未随本站及公开仓库分发。命令用于说明调用方式,复现需自行准备对应实现、数据与环境。

一句话带走:检索和草稿外面还要有一条可信入口,把身份、请求预算和失败记录接成同一件事。

我们搭一个虚构的设备维修台。Alice 查型号资料,再保存“人工核对铭牌”的工单草稿。已有 core 负责当前租户与文档权限,workflow 负责草稿和审批;本节只增加小型本地服务层,不接模型或真实身份提供商。

先看服务代码(examples/knowledge-assistant/product_lab.py)和契约测试(examples/knowledge-assistant/test_product_lab.py)。这节把 AI 全栈的调用层、认证与多租户、限流与配额、可观测性接到同一请求里。原则来自这些章节;下面的维修台和数字是原创教学场景。

一个请求走过哪些门

宿主传入 opaque 凭证、稳定 request_id、业务参数
→ workflow.verify_token 检查当前凭证
→ 服务端构造固定 tenant / subject / scopes
→ 检查参数与所需 scope
→ 认领请求编号、限流、熔断、并发槽位
→ SQLite 同一事务扣 1 个教学请求单位并写请求账本
→ 可选的只读故障传输夹具
→ core.retrieve 或 workflow.draft
→ 再验当前凭证;搜索证据还要检查当前 ACL / 修订
→ 持久化终态及关联审计

模型或业务参数只能是 {"action":"search","query":"…"},或者 {"action":"draft","title":"…","body":"…"}。多一个 tenant、subject 或 scopes 字段就拒绝。凭证、请求编号、配额初始化属于可信宿主;模型不能签发凭证、重置余额或选择身份。approve、execute 也不是入口支持的动作。

这里的 opaque 凭证复用 workflow.issue_token/verify_token:数据库只存凭证摘要,每次核对 audience、到期时间和吊销状态。它是本地测试夹具,不是 OAuth/OIDC 服务。本节没有编造 JWT,也没有引入 HTTP 服务器。

服务层从已验证凭证取得身份,从当前 core 核对文档授权。下面运行示例,观察两步检查如何衔接。

跑出搜索、草稿和失败重放

以下展示示例 knowledge-assistant 目录内的命令:

python -m venv .venv
.venv/Scripts/python.exe product_lab.py demo --db .runtime/product.db --output .runtime/product-run.json
.venv/Scripts/python.exe test_product_lab.py --events .runtime/product-tests.json

本节只用标准库和已有示例代码,不需要安装模型或联网。程序会保护旧记录;第二次复跑,请给 --db、--output、--events 换新文件名。

2026-10-11 审查修复后的实际运行 JSON(examples/knowledge-assistant/validation/product-demo-review-20261011.json)记录了搜索 completed、草稿 pending、故障 downstream_unavailable,然后同一失败编号的重放得到 request_repeated。初始 10 个单位剩 7 个,tickets_created 是 0。搜索真正调用已有 BM25 检索;草稿真正写入 runs,没有自动审批。

搜索成功表示允许访问的证据被返回,不表示自然语言答案正确。已有词项基线会把相邻型号排在前面;维修台把核对型号留给人工。本节既不产生模型答案,也不把注入的 503 写成真实供应商故障。

先把扣额规则讲清

余额单位固定叫 teaching request units(教学请求单位),不是模型 token,不是人民币或美元。每个准入请求扣 1 个单位,最多 2 次只读传输尝试也只扣这 1 个。

到了哪一步 本次扣额 编号之后能否再用
凭证、参数或 scope 检查失败 0 未认领,可修正后重试
有效请求因限流、熔断、并发、配额或准入前取消被拒 0 已写终态,重复编号拒绝
成功准入 1 写入 in_flight;并发重放拒绝
准入后成功、失败或取消 已扣的 1 保留 终态重放拒绝,不返还旧证据
同一编号换业务正文 0 request_conflict

失败后想开展新工作,需要新编号;这是新请求,会重新检查凭证、权限与余额。不能用新编号冒充同一操作的安全恢复。进程突然退出留下的 in_flight 也会拒绝重放,本例没有自动清算或退款机制。

额度扣减使用带条件的 UPDATE ... remaining>=1,与请求认领处在同一个 BEGIN IMMEDIATE 事务。重复编号与扣额之间没有“先查再扣”的并发缝隙。provision 只能首次建立余额,再调用不会把已消费额度补回来。

审计中的 charged_units 是该请求截至此事件的扣额回执,多个阶段都会写 1;不能把所有审计行相加当账单。实际扣额只按 product_requests.charged 汇总。

把最容易混淆的边界跑出来

24 项测试和原始审计(examples/knowledge-assistant/validation/product-tests-review-green-20261011.json)覆盖过期、吊销、错误 audience、缺 scope、越租户、并发扣额、编号冲突、限流、熔断、取消、截止时间和日志脱敏。

其中并发配额实验用真实 SQLite、12 个线程和 12 个独立服务对象争用同一余额 3;实际只有 3 个成功、9 个 quota_exhausted,余额为 0。它证明这次本地账本没有超卖,不是吞吐量或分布式压测。

限流采用进程内滑动窗口:默认同租户同用户在 10 秒内最多准入检查 5 个新请求;进入窗口的请求即使后来因熔断或余额失败,仍占一个速率位置。传输失败达到阈值后打开熔断;冷却结束只允许一个恢复探测先行。恢复探测的认领和提交都在同一锁区间,测试专门把线程停在解锁边界来检查第二个请求会不会偷跑。

这些窗口、熔断器和并发槽位只属于一个 ProductService 对象。多开对象或进程会有各自的状态;持久化配额共享不等于限流也共享。要做真实多实例服务,需要另外设计共享限流、共享熔断及其故障语义。

传输夹具只在检索或草稿前做只读探测,429、503 和超时最多重试 2 次。它与已有 deployment_lab 的故障演练思路一致,但本例独立保存服务级终态。默认协作截止时间为 5 秒,检查发生在操作前后;不能杀掉已经阻塞的传输或 SQLite 调用。接真实网络还需要适配器自己的超时和取消契约。

取消之后,草稿可能还在

有一个测试先让真正的 workflow.draft 提交,再设置取消标记。请求终态是 cancelled,已扣单位保留,草稿仍为 pending。审计写下对应 workflow_run_id,让可信操作者能找到它;本地外层取消不会撤销已经提交的另一笔事务。

审批继续使用单独的 workflow.approve,执行继续使用带执行 scope 的 workflow.execute。操作者要检查草稿、绑定动作指纹和有效期限,再按已有工作流处理;这些函数没有出现在本节业务动作白名单中。

搜索不缓存允许访问过的证据。吊销后的重复请求先过当前凭证检查;新编号重新执行 core ACL 过滤。测试还在真实检索后修改 ACL,确认交付前的引用检查会拒绝旧证据。产品响应只提供复验后的 context 和状态、模式、长度、耗时;内部候选列表属于检索诊断,不返回给调用方。新增测试只撤掉未进入 context 的低排名文档:合法 context 仍成功交付,但已撤权候选的编号与分数不会出现在产品响应。这是操作边界的复验,不承诺权限变更与屏幕显示之间存在跨系统原子事务。

走神救援

先看输出里的 trace_id,再到 audit 找同一编号。凭证失败查 audience、到期与 revoked;request_repeated 查 original_trace_id,不要期待缓存答案;余额不足查 product_requests 的一次扣额记录。发生取消且审计有 workflow_run_id,检查对应 pending 草稿后再决定下一步。

如果只看到 completed 就想写“企业级服务上线”,回到运行记录的 mode:真实验证的是本地 SQLite 与业务边界;传输错误、时间跳变和取消标记是注入实验。真实 IdP、网络超时、分布式状态、真实模型质量、token/$ 计费和崩溃后的自动恢复都未验收。

折叠自查

检查点 1. 请求体能选择租户吗?

不能。额外身份字段被拒绝,身份从当前验证通过的 opaque 凭证构造。

检查点 2. 两个请求都读到余额 1,会扣成负数吗?

本例用条件扣减和同一 SQLite 写事务认领编号;真实线程实验没有超卖,余额还有 CHECK 约束。

检查点 3. 503 重试两次会扣两单位吗?

不会。准入时一次扣 1 教学请求单位,传输尝试不另扣。

检查点 4. 失败编号再发一次为什么不返回原答案?

服务保留请求终态,拒绝重放;它没有答案缓存,也不会返还撤权前证据。

检查点 5. 取消意味着工单草稿没保存吗?

不一定。草稿可能已提交为 pending;审计的 workflow_run_id 用于检查,取消不自动撤销业务事务。

检查点 6. 5 秒预算能中断所有调用吗?

不能。它是操作前后的协作检查,真实适配器需要网络超时和取消能力。

检查点 7. 共享 SQLite 配额意味着分布式限流吗?

不意味着。限流窗口、熔断和槽位只在单对象、单进程内共享。

检查点 8. 审计里多行 charged_units=1 可以相加吗?

不能。它们是同一请求各阶段的累计回执,实际扣额按 product_requests.charged 汇总。

打卡记录保存在你的浏览器里,首页能看到总进度