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)?;
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 必须:
- 先调用
request,由 SDK 记录 stream=true 与请求上下文。
- 每收到一个上游 chunk 就调用
feed,并立即转发追加出的字节。
- 上游结束后调用
finish,转发尾帧并检查 Termination。
- 在合适时机调用
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。