llmwire 0.1.0

Bidirectional, stateless, transport-neutral LLM wire protocol conversion kernel
Documentation

llmwire

llmwire 是一个双向、默认无状态、可嵌入任意 host 的 LLM wire protocol 转换核。

Host 把原始请求或响应字节交给请求级 Converter,它负责:

  • SSE 分帧与跨 chunk 拼接
  • 源协议解析
  • 协议无关 IR 转换
  • 目标协议序列化
  • 降级与不支持的显式 Report

llmwire 不发送 HTTP、不管理连接、不保存跨请求状态,也不绑定 async runtime。

状态:M0 至 M5 已完成,P0 至 P2 验证增强已完成。当前版本为 0.1.0。 已验证范围与尚未覆盖的真实 API 场景见 docs/TESTING.md。

支持范围

能力 状态
OpenAI Chat Completions 请求、响应、流式
Anthropic Messages 请求、响应、流式
OpenAI Responses 无状态请求、响应、流式
三协议双向文本转换 支持
response id / model 透传 target 上报值;model 缺失时统一空字符串
tool call / tool result 支持,ID 字节保真
thinking / signature / encrypted reasoning 支持或显式降级,不伪造
usage / cache usage 保留未知与零的差异
图片输入 URL / Base64 支持,三协议间映射
图片 file_id 明确不支持
有状态 Responses 明确不支持

核心依赖约束:除 serde、serde_json、thiserror、bitflags 外,不引入运行时依赖。

安装

从 crates.io 安装:

cargo add llmwire

也可以直接写入 Cargo.toml:

[dependencies]
llmwire = "0.1"

本地开发时可以使用仓库路径:

[dependencies]
llmwire = { path = "../llmwire" }

要求 Rust edition 2021。

非流式用法

converter(src, dst, caps) 中的方向约定:

  • src:客户端正在使用的协议
  • dst:上游后端正在使用的协议
use llmwire::{converter, resolve, ProtocolId};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut converter = converter(
        ProtocolId::Chat,
        ProtocolId::Messages,
        resolve(ProtocolId::Chat, ProtocolId::Messages, "claude-model"),
    )?;

    let client_request = br#"{
        "model": "claude-model",
        "messages": [{"role": "user", "content": "hello"}],
        "max_completion_tokens": 32
    }"#;

    let mut upstream_request = Vec::new();
    converter.request(client_request, &mut upstream_request)?;
    // Host 将 upstream_request 发给 Messages 后端。

    let backend_response = br#"{
        "id": "msg_1",
        "type": "message",
        "role": "assistant",
        "content": [{"type": "text", "text": "world"}],
        "model": "claude-model",
        "stop_reason": "end_turn",
        "usage": {"input_tokens": 3, "output_tokens": 2}
    }"#;

    let mut client_response = Vec::new();
    converter.response(backend_response, &mut client_response)?;

    let report = converter.take_report();
    println!(
        "report: {} unmapped, {} warnings",
        report.unmapped.len(),
        report.warnings.len()
    );

    println!("{}", String::from_utf8_lossy(&client_response));
    Ok(())
}

完整示例:

cargo run --example nonstream

流式用法

流式模式下,host 必须:

  1. 先调用 request,由 SDK 记录 stream=true 与请求上下文。
  2. 每收到一个上游 chunk 就调用 feed,并立即转发追加出的字节。
  3. 上游结束后调用 finish,转发尾帧并检查 Termination。
  4. 在合适时机调用 take_report。
use llmwire::{converter, resolve, ProtocolId, Termination};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut converter = converter(
        ProtocolId::Chat,
        ProtocolId::Messages,
        resolve(ProtocolId::Chat, ProtocolId::Messages, "claude-model"),
    )?;

    let client_request = br#"{
        "model": "claude-model",
        "stream": true,
        "messages": [{"role": "user", "content": "hello"}],
        "max_completion_tokens": 32
    }"#;
    let mut upstream_request = Vec::new();
    converter.request(client_request, &mut upstream_request)?;

    let upstream_chunk = concat!(
        "event: message_start\n",
        "data: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_1\",\"model\":\"claude-model\"}}\n\n",
        "event: content_block_start\n",
        "data: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}}\n\n",
        "event: content_block_delta\n",
        "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"hello\"}}\n\n",
        "event: content_block_stop\n",
        "data: {\"type\":\"content_block_stop\",\"index\":0}\n\n",
        "event: message_delta\n",
        "data: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"end_turn\"}}\n\n",
        "event: message_stop\n",
        "data: {\"type\":\"message_stop\"}\n\n",
    );

    let mut client_stream = Vec::new();
    converter.feed(upstream_chunk.as_bytes(), &mut client_stream)?;

    let mut tail = Vec::new();
    let termination = converter.finish(&mut tail)?;
    client_stream.extend_from_slice(&tail);
    assert_eq!(termination, Termination::Explicit);

    println!("{}", String::from_utf8_lossy(&client_stream));
    Ok(())
}

完整示例:

cargo run --example streaming

能力与策略

简单的协议对配置可以使用:

let caps = llmwire::resolve(
    llmwire::ProtocolId::Chat,
    llmwire::ProtocolId::Messages,
    "claude-model",
);

需要按模型覆盖策略时使用 StaticHost:

use llmwire::{
    Host, ModelProfile, ProtocolId, StaticHost, ThinkingPolicy, UnknownModelPolicy,
};

let host = StaticHost::with_unknown_policy(UnknownModelPolicy::Reject)
    .with_profile(
        "claude-model",
        ModelProfile {
            thinking: Some(ThinkingPolicy::Passthrough),
            max_output_tokens: Some(8192),
            ..ModelProfile::default()
        },
    );

let caps = host.capabilities(
    ProtocolId::Chat,
    ProtocolId::Messages,
    "claude-model",
)?;
# Ok::<(), llmwire::Error>(())

能力策略描述的是“这条路由允许采用什么转换方式”,不是协议本身的能力表。

错误与 Report

llmwire 使用双信道表达问题:

  • Result::Err:适用于尚未向客户端发出成功响应前的失败。
  • Converter::feed 中的流内失败:写入目标协议 error 事件,并记录到 Report;不会混用为 Ok(Termination::Explicit)。
  • Report:记录字段降级、不可表达内容与策略阻断。

典型处理方式:

let report = converter.take_report();
for item in report.unmapped {
    eprintln!(
        "unmapped field={} reason={:?} severity={:?}",
        item.field, item.reason, item.severity
    );
}

take_report 会清空当前已累积的报告。

Host 的职责

llmwire 只处理 wire 字节,host 仍需负责:

  • HTTP 请求、认证、超时与重试
  • 路由选择与上游连接
  • 从请求体中提取模型名并选择后端
  • 把 out 字节写入客户端或上游
  • SSE 出口关闭代理缓冲、gzip 与网关聚合
  • 客户端断连、网络异常与上游取消

已知限制

  • 不伪造 signature、redacted_thinking 或 thinking 内容。
  • 不重算或改写客户端传入的 cache_control 断点。
  • 不支持有状态 Responses 请求,例如 previous_response_id 与 store=true。
  • Chat 流式 n > 1 当前显式返回 Unsupported。
  • 图片仅支持远程 http(s) URL 与 Base64 payload;file_id 不支持。
  • 核心不下载图片、不上传图片、不生成托管 URL。
  • Live 矩阵当前以本地网关为主,官方端点矩阵尚未执行。
  • Messages thinking/signature live 测试仍为 skipped,不能视为该路径已获真实 API 验证。

文档

  • docs/DESIGN.md:架构、公开 API 与不可协商约束
  • docs/spec/IR.md:协议无关 IR
  • docs/spec/STREAMING.md:流式事件与 FSM
  • docs/spec/chat.md、docs/spec/messages.md、docs/spec/responses.md:协议映射
  • docs/spec/IMAGE.md:图片输入规则
  • docs/TESTING.md:测试策略、live API 与当前验证矩阵
  • docs/PLAN.md:里程碑与完成定义
  • docs/README.md:完整文档地图

许可证

MIT。详见 LICENSE。

开发

cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked -p llmwire
pwsh -NoProfile -File scripts/check-core-deps.ps1
pwsh -NoProfile -File scripts/check-live-gate.ps1

Live API 测试默认 ignored,只有显式运行 --ignored 时才访问网络。配置方式见 docs/TESTING.md §7。