面向 provider-neutral LLM 的 Rust 现场手册。

Usage Guide

从 canonical path 开始。

OmniLLM 默认路径刻意保持保守：一个类型化生成请求、一个 gateway、多个 provider 后端。应用代码围绕 LlmRequest 与 LlmResponse，运行时处理运维问题。

默认非流式生成使用 Gateway::call；canonical streaming 使用 Gateway::stream。当产品需要 provider-neutral generation，而不是手写每个 provider adapter 时，这是首选入口。

let gateway = GatewayBuilder::new(ProviderEndpoint::openai_responses())
    .add_key(KeyConfig::new("sk-key-1", "prod-1").rpm_limit(500))
    .budget_limit_usd(50.0)
    .request_timeout(Duration::from_secs(45))
    .build()?;

let response = gateway.call(request, CancellationToken::new()).await?;

Architecture

两种模式，共用一套预算账本。

OmniLLM 提供规范化 canonical 模式与显式 primitive 模式。前者让生成行为可移植，后者为无法自然映射到单一生成 schema 的 provider API 保留原始请求与响应。

规范化应用契约；当 provider API 本身就是产品时，保留 provider 契约。OmniLLM protocol posture

Runtime Profiles

端点名称描述 wire shape。

运行时配置使用 EndpointProtocol；底层解析、发射与转码使用 ProviderProtocol。ClaudeMessages、GeminiGenerateContent 这类名称描述的是 wire shape，而不是营销偏好。

Native APIs

Primitive mode 保留 provider 原生 API。

Primitive 调用是显式增量能力。它适用于那些 provider 原生 API 契约就是产品行为一部分的场景。 PrimitiveRequest, primitive_call, primitive_stream, 以及 primitive_realtime 保持 primitive path 的增量语义，而不是把原始 provider API 强行塞进 canonical generation conversion。

let request = PrimitiveRequest::json(
    ProviderPrimitiveKind::ImagesGenerate,
    serde_json::json!({
        "model": "gpt-image-1",
        "prompt": "A blueprint-style gateway diagram"
    }),
);

let raw = gateway.primitive_call(request, CancellationToken::new()).await?;

Conversion

损耗要报告，不能隐藏。

Transcoding 会通过 ConversionReport<T> 返回显式 bridge metadata。调用方可以检查 bridged、lossy 与 loss_reasons，而不是猜测哪些 provider-specific 字段被丢弃。

let report = transcode_api_request(
    WireFormat::OpenAiChatCompletions,
    WireFormat::OpenAiResponses,
    raw_chat,
)?;

assert!(report.bridged);
assert!(!report.lossy);
for reason in report.loss_reasons {
    tracing::warn!(%reason, "provider bridge dropped data");
}

API Reference

API surface 按使用意图分层。

把 API 当成多层结构来读：先用稳定的应用契约，再选择任务对应的 endpoint family；只有当原始 provider 契约本身很重要时才进入 primitive mode，并且每条调用路径都保留 transport、replay 与运维信号。

Registry

Provider 覆盖按能力声明。

Provider 支持以端点能力与 primitive 能力表达，而不是宣称完整 SDK parity。这样 registry 能更准确地描述 transport shape、request path、response preservation 与 settlement 行为。

Testing

Fixture 要既有用又安全。

Record/replay 测试需要可审查且不泄露密钥的工件。OmniLLM 提供 ReplayFixture、sanitize_transport_request、sanitize_transport_response 与 sanitize_json_value 来支持安全 fixture 工作流。

1. 只在受控集成运行中记录真实 transport request 与 response。
2. 脱敏 auth header、query token、JSON secret，以及大体积 binary/base64 字段。
3. 把 fixture diff 当成 API contract 审查，而不是不透明 snapshot。
4. 修改 protocol bridge 或 provider profile 前，先用 deterministic fixture replay。

let sanitized = sanitize_transport_request(recorded_request);
let fixture = ReplayFixture::from_transport(sanitized, response);
fixture.write_json("tests/fixtures/openai_responses.basic.json")?;

Operations

运行时状态应当出现在接口里。

生产服务可以检查 gateway.pool_status() 与 gateway.budget_remaining_usd()。这些接口暴露 Key 可用性、inflight token pressure、RPM pressure、circuit state，以及预留与结算后的剩余预算。

信号请求失败时，OmniLLM-specific errors 会告诉运维问题属于 pool availability、spend policy 还是 protocol conversion。

Production

上线前，先明确运行契约。

运行时提供基础能力，但生产可用性来自把预算、取消、回放与 provider 行为显式放进服务边界。

1. 优先为可移植生成选择 canonical protocol，再决定是否进入 provider primitive。
2. 为每个生产 Key 配置明确 label、RPM 限制、冷却行为与预算假设。
3. 所有 gateway 路径都使用 CancellationToken 与 request timeout，包括 primitive 和 stream。
4. 把 ConversionReport 纳入协议转码验收标准，不要默认所有字段都能无损桥接。
5. 回放夹具必须先脱敏 auth header、query secret 与大体积二进制字段。
6. 上线前把 pool_status、budget_remaining_usd 与 OmniLLM 错误类别暴露给运维。

AI-native Project

Skill 会教 agent 使用真实库边界。

内置 OmniLLM Skill 给 coding agent 仓库级信号，而不是泛泛的 Rust SDK 猜测。它围绕 GatewayBuilder、ProviderEndpoint、EndpointProtocol、WireFormat、ReplayFixture、primitive calls 与 OmniLLM runtime errors 调优。

1. 把 Skill 安装到 Claude Code、Codex、OpenCode 或兼容 Claude Skill 的运行器。
2. 让 agent 协助 gateway setup、endpoint selection、protocol transcoding、replay fixture generation 或 OmniLLM error debugging。
3. 用真实 examples、tests、endpoint profiles、conversion reports 与 runtime surfaces 校验回答。

# Codex / Claude Code / OpenCode
npx @vercel-labs/skills install github:aiomni/omnillm/skill

# Rust runtime
cargo add omnillm