jeremychone/rust-genai

Rust multiprovider generative AI client (Ollama, OpenAi, Anthropic, Gemini, DeepSeek, ZAI, OpenRouter, FireworksAI, xAI/Grok, Groq,, ...)

概述

genai 是一个 Rust 库，为开发者提供了一个单一、易用的 API，用于与许多大语言模型（LLM）提供商进行通信。它抽象了提供商（OpenAI、Anthropic、Gemini、Ollama、Bedrock 等）之间的差异，同时仍允许您在每个提供商存在时使用其原生协议。实际上，您创建一个 Client，使用系统/用户消息构建一个 ChatRequest，并使用模型名称（例如 gpt-5.6-luna）或命名空间名称（例如 qwen_cloud::qwen3.8-max）调用 exec_chat（或流式变体）。

主要功能

功能	对您意味着什么
多提供商支持	内置 27+ 提供商和 200+ 模型。库会根据模型名称选择正确的适配器，或者您可以使用 `namespace::model` 语法强制指定。
原生协议适配器	当提供商提供专有 API（例如 Anthropic、Gemini、Bedrock）时，genai 直接与其通信，保留推理预算、工具调用元数据和流式帧等高级选项。
OpenAI 兼容后备	对于暴露 OpenAI 风格端点的服务（Ollama、自定义自托管服务器、Groq 等），genai 使用通用的 OpenAI 兼容适配器。
流式与帧检查	`exec_chat_stream` 返回 `ChatFrame` 流；您可以附加一个 `ChatFrameSink` 来检查原始帧以进行调试或自定义处理。
工具/函数调用	提供商中立的 `ToolChoice` 和内置工具结构（例如 `WebSearch`）允许您在 Anthropic、OpenAI、Gemini 等上使用工具调用，而无需编写特定于提供商的代码。
推理努力控制	像 `ReasoningEffort::High` 这样的枚举映射到特定于提供商的旋钮（例如 Anthropic 的 `max_tokens` 或 OpenAI 的 `temperature`）。
图像分析	为接受图像的提供商（OpenAI Vision、Gemini Flash‑2、Anthropic）提供了简单的辅助函数。
自定义端点与认证	设置环境变量（`GENAI_1_ENDPOINT`、`GENAI_1_API_KEY`、`OMLX_ENDPOINT` 等）或实现 `ServiceTargetResolver` 将客户端指向任何 OpenAI 兼容服务器。
TLS 后端选择	在编译时选择 native-tls、rustls 或 OpenSSL。
OpenTelemetry 集成	可选的 `otel` 功能添加了 GenAI 语义约定追踪。

工作原理

创建客户端 – let client = Client::new()?;（现在可能失败，返回 Result）。
模型解析 – 库从模型前缀（gpt‑* → OpenAI, claude‑* → Anthropic 等）推断 AdapterKind。您可以使用 namespace::model 覆盖。适配器知道正确的 HTTP 端点、认证头和请求格式。
聊天请求 – 使用一系列 ChatMessage（系统、用户、助手）构建 ChatRequest。可选的 ChatOptions 允许您设置温度、最大令牌数、工具选择、额外正文等。
执行 – 对于单个响应，调用 client.exec_chat(model, request, None).await?；对于流式响应，调用 exec_chat_stream。
结果处理 – 返回的 ChatResponse 为您提供生成的文本（first_text()）、工具调用数据以及需要的原始流式帧。

示例（简化）

use genai::{Client, chat::{ChatMessage, ChatRequest}};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1️⃣ 创建客户端（读取环境变量以获取 API 密钥）
    let client = Client::new()?;

    // 2️⃣ 构建一个简单的聊天请求
    let req = ChatRequest::new(vec![
        ChatMessage::system("You are a concise assistant"),
        ChatMessage::user("Why is the sky red?"),
    ]);

    // 3️⃣ 调用任何模型 – 这里是一个 OpenAI 兼容的模型
    let resp = client.exec_chat("gpt-5.6-luna", req, None).await?;
    println!("Answer: {}", resp.first_text().unwrap_or("<none>"));
    Ok(())
}

何时使用 genai

您需要在提供商之间切换（例如，在 OpenAI、Anthropic 和本地 Ollama 模型上测试提示词），而无需重写请求代码。
您想要一个单一的 Rust crate，而不是引入许多特定于提供商的 SDK。
您关心提供商特定功能，如 Anthropic 的 tool 缓存、Gemini 的结构化输出或 Bedrock 的签名推理块 – genai 在保持公共接口的同时公开它们。
您正在构建一个服务或 CLI，可能在开发时本地运行（Ollama），在生产时云端运行（OpenAI、Bedrock）。

限制 / 注意事项

方面	说明
API 深度	该 crate 专注于聊天/补全、流式和少量多模态辅助。功能全面的 SDK（例如 async-openai）可能有更多端点（嵌入、微调、审核）。
提供商特定怪癖	虽然大多数旋钮已统一，但一些高级功能（例如 OpenAI 的 `logprobs`、Azure 资源特定头）尚未暴露。
异步运行时	需要 Tokio（或任何实现 `AsyncRead/Write` 的运行时）。
版本节奏	快速发布（0.6 → 0.7）可能引入破坏性更改；升级时请查阅迁移指南。

开始使用

添加到 Cargo.toml：
```
genai = "0.6"
```
为您计划使用的提供商设置适当的环境变量（例如 OPENAI_API_KEY、ANTHROPIC_API_KEY）。
运行捆绑的示例之一，例如 cargo run --example c00-readme。

社区与贡献

Crates.io –
GitHub – 问题、PR 以及贡献者 BIG-THANKS.md 列表。
视频教程 – YouTube 播放列表介绍了设置、模型映射和添加新提供商。
功能标志 – 选择 TLS 后端（native-tls、rustls-tls、openssl-tls）和可选的 OpenTelemetry（otel）。

TL;DR

genai 是一个 Rust 优先、提供商无关的 LLM 聊天 API 包装器。编写一段 Rust 代码，将其指向数十种模型中的任何一种——从 OpenAI 的 GPT‑4o 到本地运行的 Ollama 模型——即可获得一致的响应，同时仍能利用每个服务的独特功能。