驱动¶
Driver 是 Legate 的协议适配边界。它声明自己支持的精确入站协议契约，并把请求转换成 Core 可以验证和执行的上游计划；它也负责把上游 buffered 响应或流事件转换回原入站协议。
Driver 不拥有网络、凭据、选路或重试权限。这些职责始终属于 Legate Core。
Core 与 Driver 的边界¶
| 能力 | Legate Core | Driver |
|---|---|---|
| API 密钥、Workspace 与模型组授权 | 是 | 否 |
| 接入点选择、tier、weight、资源 admission 与熔断 | 是 | 否 |
| 上游凭据和 HTTP I/O | 是 | 否 |
| SSE / NDJSON framing、超时与响应提交 | 是 | 否 |
| 上游相对路径、query、header 与 body plan | 验证并执行 | 声明 |
| 协议请求、响应和流事件转换 | 管理边界 | 是 |
| Usage 与特殊 Outcome 语义 | 汇总并持久化 | 可报告 |
Driver 在 Bind 时只收到非敏感配置、可用 endpoint ref，以及 credential slot 的名称和 configured 布尔值。
精确引用¶
接入点始终绑定精确 Driver Ref：
builtin://openai-chat-compatible@1
builtin://openai-responses-compatible@1
builtin://openai-image-compatible@1
builtin://anthropic@1
profile://workspace-42/acme@sha256:<64 位小写十六进制摘要>
builtin:// 随 Legate 二进制发布；profile:// 指向某个 Workspace 上传的不可变 WASM 制品。不支持 latest、版本范围或解析失败回退。接入点始终显式选择一个精确引用。
当前协议契约¶
文本：
| Contract | 调用入口 | 模式 |
|---|---|---|
openai.chat_completions/2026-07-18 |
POST /v1/chat/completions |
buffered、SSE |
openai.responses/2026-07-18 |
POST /v1/responses |
buffered、SSE |
anthropic.messages/2026-07-18 |
POST /v1/messages |
buffered、SSE |
图片：
| Contract | 调用入口 | 模式 |
|---|---|---|
openai.images.generations/2026-07-19 |
POST /v1/images/generations |
buffered |
openai.images.edits/2026-07-19 |
POST /v1/images/edits |
buffered multipart |
Contract ID 是不可变的协议版本，不是模糊的“OpenAI compatible”标签。模型组和 Driver 必须对同一个精确 Contract 达成一致。
内置 Driver¶
| Driver | 类型 | 上游目标 | 管理能力 |
|---|---|---|---|
builtin://openai-chat-compatible@1 |
text | OpenAI Chat Completions | 列出模型 |
builtin://openai-responses-compatible@1 |
text | OpenAI Responses | 列出模型 |
builtin://anthropic@1 |
text | Anthropic Messages | 列出模型 |
builtin://openai-image-compatible@1 |
image | OpenAI Images | 无 |
三个文本 Driver 均声明全部三种文本 Contract，并同时支持 buffered 与 SSE。它们之间的区别是上游目标协议，而不是调用方入口。
生命周期¶
- 内置 Driver 在进程启动时注册。
- WASM Profile 上传后经过 Manifest、ABI、制品和资源检查再注册。
- Endpoint 配置 generation 建立并冻结 Binding。
- 请求只使用已冻结的 Binding；每个真实候选拥有独立 Attempt，结束时恰好 Close 一次。
文本流由 Core 解帧，Driver 只转换协议事件。图片二进制由 Core 以不透明 BlobRef 持有，Driver 通过有界 BodyPlan 组合 multipart 或 Base64 输出。对于内嵌 Base64 图片的供应商 JSON，Image Driver 可以声明 typed 提取路径；Core 负责流式解析和解码，Driver 只收到小型 JSON 骨架、路径元数据和不可读的 BlobRef。
WASM Profile¶
Console 的“驱动”页面分为“内置驱动”和“WASM 驱动”。上传需要一份 Manifest JSON 和一个 .wasm 制品；成功后会生成不可变 profile ref。仍被接入点引用的版本不能删除。
WASM ABI v1 不提供 WASI、网络、文件系统、环境变量或任意宿主回调。Driver trap、超时、非法内存或非法计划都会被 Core 转换为受控失败。详细流程见开发 Driver。