摘要
我们把 /v1/orchestrations 设计为面向智能体运行时的公开编排协议：一次模型调用、工具发现、工具调用、工具结果、推理增量和最终输出被组织为可流式消费的 orchestration 对象。本文根据已实现源码、协议回归测试和实现记录，说明它承诺的边界、工具模型、事件投影与当前性能证据。
本研究不把协议层描述成“让模型更快”的魔法。它统一模型生态的鉴权、限额、路由、计量和日志控制面，并把不同下游格式投影为稳定的 orchestration.* 事件；模型排队、prefill 与首 token 解码仍由模型服务、输入长度、缓存和网络决定。主节点同机内网的六次短请求证明 JSON 与 SSE 都能完成事件闭环，但样本量不足以发布生产 SLA、P95/P99 或成本优势。
一、公开协议边界
对外资源由 POST /v1/orchestrations、POST /v1/orchestrations/compact 与同路径 WebSocket 会话组成。主对象使用 orch_ 前缀与 orchestration 类型；状态为 queued、in_progress、completed、failed 或 incomplete。这些名字属于我们的公开契约，不要求客户端推断供应商、分区、时间或账户信息。
orchestration.* 事件。客户端消费的是公开契约，而不是路由模型的原生事件格式。输入面覆盖 model、instructions、input、tools、tool_choice、parallel_tool_calls、reasoning、store、stream、include、service_tier、prompt_cache_key、text 与 client_metadata。后者会被规范化为公开元数据；鉴权上下文、代理请求、敏感字段和运行时日志对象不会进入模型输入或公开响应。协议专注于可观察的模型—工具回合，不将自身定义为任务队列或通用工作流引擎。
二、流式事件与工具过程
SSE 的 event: 与 JSON type 统一使用 orchestration.* 命名空间。客户端可在最终文本之前接收 orchestration.created、输出项增加/结束、output_text.delta、工具参数 delta/done、推理摘要 delta、元数据以及 completed/failed/incomplete。不同模型未必暴露每一种事件，例如推理增量依赖下游能力；稳定的是事件语义和容错策略，而非把所有供应商能力伪装成等价。
工具面支持 function，并提供 namespace、tool_search、custom_tool、custom_tool_call 与 custom_tool_call_output。namespace 让宿主按能力域组织函数；tool_search 允许先发现后注入延迟加载工具，减少初始 schema 压力；自定义工具项保留调用和回填。MCP 可以担任工具目录或执行后端，但它解决的是工具/资源互操作，Orchestrations 解决的是一次模型回合的状态与面向用户的事件投影。
三、性能模型与观测点
我们把首次可见文本延迟拆为 ingress、鉴权策略、规范化、路由、供应商排队、模型 prefill、首次解码、流转换和网络。协议层最直接新增的是规范化与流投影；其规模随请求或事件体线性增长，预期通常小于远程模型推理，但仍必须靠基准验证。实现记录 TTFB、TTFE、TTFT，并关联模型标识和请求体字节数，不公开提示词、授权头或内部网络信息。
T_TTFT = T_ingress + T_auth_policy + T_normalize + T_route + T_provider_queue + T_model_prefill + T_first_decode + T_stream_transform + T_network
SSE 的价值是允许前端在完整回答之前渲染，而不是承诺缩短总完成时间。tool_search 能以额外发现回合换取较小的初始工具定义；prompt_cache_key 只是缓存提示，命中和收益取决于路由策略；/compact 降低未来 prefill 的可能成本，同时自身消耗一次服务或模型预算。这些取舍必须按同一模型、区域、并发、token 预算和缓存条件测量。
四、主节点同机内网实测
2026-07-14，我们对 vauix/deepseek-v4-flash 进行了六次串行、固定短输入、无工具的真实请求：三次 JSON、三次 SSE。路径直连主节点本机 LiteLLM 数据面，绕过公网域名、边缘网关和跨机网络；它测得的是本机协议执行链路。请求不主动复用会话，也没有声明缓存键，运行时缓存、连接复用或上游排队仍可能造成波动。
JSON 三次均成功，响应头与总时延中位数为 1,858 ms。SSE 三次均完成公共事件闭环，响应头中位数 138 ms、首体字节中位数 140 ms、TTFT 中位数 160 ms、总时延中位数 237 ms。SSE 观测到 created、in_progress、输出项/内容项增量、output_text.delta、对应 done 事件与 completed。这支持“事件能在本机数据面较早到达”的有限结论；JSON 242–2,942 ms、SSE 214–1,550 ms 的跨度也说明不能从三次样本推出稳定分位数。
| 形态 | 运行 | HTTP / 状态 | 响应头 / 首体字节 ms | TTFT ms | 总时延 ms | Token / 响应字节 |
|---|---|---|---|---|---|---|
| JSON | 1 | 200 / completed | 2,941 / — | — | 2,942 | 9 / 22 / 31 |
| JSON | 2 | 200 / completed | 1,858 / — | — | 1,858 | 9 / 22 / 31 |
| JSON | 3 | 200 / completed | 242 / — | — | 242 | 9 / 22 / 31 |
| SSE | 1 | 200 / 完整事件流 | 138 / 140 | 160 | 237 | 2,992 bytes |
| SSE | 2 | 200 / 完整事件流 | 117 / 120 | 140 | 214 | 2,992 bytes |
| SSE | 3 | 200 / 完整事件流 | 1,435 / 1,437 | 1,478 | 1,550 | 2,992 bytes |
五、与主流接口的关系
OpenAI Responses 的对象化 response 生命周期、SSE typed events、函数/自定义工具、parallel_tool_calls、prompt_cache_key、service_tier 与 store 为行业接口提供了可验证经验；我们吸收这些概念作为兼容目标，但公开对象、事件和演进节奏始终以 orchestration 为准。Anthropic Messages 擅长以内容块呈现工具使用，Gemini Function Calling 把函数声明/响应嵌入生成循环；我们不试图替代它们，而是让路由模型进入统一网关控制面。MCP 也不是竞争对象：它可提供工具与资源，协议运行时负责把工具过程纳入模型回合。
六、可靠性与安全边界
客户端必须处理 failed 与 incomplete，不能把缺少错误事件当作成功；工具执行是否可重试取决于调用 ID、幂等设计和宿主策略。namespace 与 tool_search 减少暴露面，却不能独自抵御提示注入、越权调用或结果投毒，执行端仍须执行身份、授权、参数校验、审计与最小权限。事件演进采取可加字段、可忽略未知事件的策略；字段删除、状态语义改变或工具项重命名应通过新版本或弃用期完成。
七、验证状态与下一步
实现记录显示顶层对象与事件命名空间转换、推理摘要索引、路由归类、内部元数据剔除、工具消息顺序和 tool_search 物化均有回归断言。当前复核没有重新执行 pytest：本地 Python 虚拟环境在测试收集前缺少标准库 encodings。这不是协议失败证据，也不能被计为重新验证通过。发布前应在干净、锁定依赖的环境运行协议测试，并建立 JSON/SSE/WebSocket 共用 conformance fixture、取消/断流测试、工具幂等与权限拒绝测试，以及按固定条件公开的性能原始聚合数据。
八、结论
Orchestrations v1 提供的是独立、可观察的模型—工具回合协议：网关吸收模型生态差异，运行时统一输入与工具编排，客户端消费稳定的对象和事件命名空间。当前实测表明本机内网的 JSON 与 SSE 路径可用，且 SSE 能较早交付文本增量；它没有证明生产吞吐、全局延迟或成本优势。后续发布将把性能、跨模型能力差集、工具安全与协议 conformance 作为独立、可复核的研究主题，而不是以单一平均延迟替代它们。