模型提供方（云端）

ADK-Rust 通过 adk-model crate 支持多个云端 LLM 提供方。所有提供方都实现了 Llm trait，因此可以在你的 agent 中互换使用。

概览

┌─────────────────────────────────────────────────────────────────────┐
│                     Cloud Model Providers                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   • Gemini (Google)    ⭐ Default    - Multimodal, large context    │
│   • OpenAI (GPT-5)    🔥 Popular    - Best ecosystem               │
│   • Anthropic (Claude) 🧠 Smart      - Best reasoning               │
│   • DeepSeek           💭 Thinking   - Chain-of-thought, cheap      │
│   • Groq               ⚡ Ultra-Fast  - Fastest inference           │
│                                                                     │
│   For local/offline models, see:                                    │
│   • Ollama     → ollama.md                                          │
│   • mistral.rs → mistralrs.md                                       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

快速对比

---

第 1 步：安装

将你需要的提供方添加到你的 Cargo.toml：

[dependencies]
# Pick one or more providers:
adk-model = { version = "2.0.0", features = ["gemini"] }        # Google Gemini (default)
adk-model = { version = "2.0.0", features = ["openai"] }        # OpenAI GPT-5
adk-model = { version = "2.0.0", features = ["anthropic"] }     # Anthropic Claude
adk-model = { version = "2.0.0", features = ["deepseek"] }      # DeepSeek
adk-model = { version = "2.0.0", features = ["groq"] }          # Groq (ultra-fast)

# Or all cloud providers at once:
adk-model = { version = "2.0.0", features = ["all-providers"] }

第 2 步：设置你的 API 密钥

export GOOGLE_API_KEY="your-key"      # Gemini
export OPENAI_API_KEY="your-key"      # OpenAI
export ANTHROPIC_API_KEY="your-key"   # Anthropic
export DEEPSEEK_API_KEY="your-key"    # DeepSeek
export GROQ_API_KEY="your-key"        # Groq

Schema 规范化

每个提供方都会在请求时自动规范化 MCP 工具 schema。你不需要做任何事——它会透明地工作。不过，下面是其内部发生的情况：

通过 Llm trait 以编程方式访问适配器：

use adk_core::{Llm, SchemaAdapter};

let adapter = model.schema_adapter();
let normalized = adapter.normalize_schema(raw_schema);

有关完整文档，请参见 Schema Normalization。

---

Gemini（Google）⭐ 默认

最适合：通用、多模态任务、大型文档

主要亮点：

• 🖼️ 原生多模态（图像、视频、音频、PDF）
• 📚 最高 2M token 上下文窗口
• 🧠 思考模式：基于级别（Gemini 3）和基于预算（Gemini 2.5），带有 thought signatures
• 💰 有竞争力的定价
• ⚡ 快速推理

完整可运行示例

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    let agent = LlmAgentBuilder::new("gemini_assistant")
        .description("Gemini-powered assistant")
        .instruction("You are a helpful assistant powered by Google Gemini. Be concise.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;
    Ok(())
}

可用模型

思考模式

Gemini 3 模型支持基于级别的思考，而 Gemini 2.5 使用基于预算的思考。在使用带函数调用的思考模式时，Gemini 2.5+ 和 3.x 模型会返回 thoughtSignature 值，必须在后续轮次中原样回传，以保留推理上下文。ADK-Rust 会自动处理这一点——当签名存在时会序列化，当 None 时则省略。

use adk_gemini::{Gemini, ThinkingLevel};

// Gemini 3: level-based thinking
let response = client.generate_content()
    .with_user_message("Solve this step by step")
    .with_thinking_level(ThinkingLevel::High)
    .with_thoughts_included(true)
    .execute().await?;

// Gemini 2.5: budget-based thinking
let response = client.generate_content()
    .with_user_message("Solve this step by step")
    .with_thinking_budget(2048)
    .with_thoughts_included(true)
    .execute().await?;

示例输出

👤 User: What's in this image? [uploads photo of a cat]

🤖 Gemini: I can see a fluffy orange tabby cat sitting on a windowsill. 
The cat appears to be looking outside, with sunlight illuminating its fur. 
It has green eyes and distinctive striped markings typical of tabby cats.

---

OpenAI (GPT-5) 🔥 热门

最适合：生产应用、可靠性能、广泛能力

主要亮点：

• 🏆 行业标准
• 🔧 出色的工具/函数调用
• 📖 最佳文档与生态系统
• 🎯 一致、可预测的输出
• 📋 结构化输出，并带有 JSON 模式强制
• 🧠 推理努力 控制，适用于 o1/o3 推理模型
• 🆕 Responses API — 面向 /v1/responses 的专用客户端，支持推理摘要、内置工具和服务端状态

完整可运行示例

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    
    let api_key = std::env::var("OPENAI_API_KEY")?;
    let model = OpenAIClient::new(OpenAIConfig::new(&api_key, "gpt-5-mini"))?;

    let agent = LlmAgentBuilder::new("openai_assistant")
        .description("OpenAI-powered assistant")
        .instruction("You are a helpful assistant powered by OpenAI GPT-5. Be concise.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;
    Ok(())
}

结构化输出（JSON 模式）

OpenAI 支持通过 output_schema 实现有保证的 JSON 输出。ADK-Rust 会自动将其连接到 OpenAI 的 response_format API：

use adk_rust::prelude::*;
use serde_json::json;
use std::sync::Arc;

let model = OpenAIClient::new(OpenAIConfig::new(&api_key, "gpt-5-mini"))?;

let agent = LlmAgentBuilder::new("data_extractor")
    .model(Arc::new(model))
    .instruction("Extract person information from the text.")
    .output_schema(json!({
        "type": "object",
        "properties": {
            "name": { "type": "string" },
            "age": { "type": "number" },
            "email": { "type": "string" }
        },
        "required": ["name", "age"]
    }))
    .build()?;

// Response is guaranteed to be valid JSON matching the schema

对于带嵌套对象的严格模式，请在每一层都包含 additionalProperties: false：

.output_schema(json!({
    "type": "object",
    "properties": {
        "title": { "type": "string" },
        "metadata": {
            "type": "object",
            "properties": {
                "author": { "type": "string" },
                "tags": { "type": "array", "items": { "type": "string" } }
            },
            "required": ["author"],
            "additionalProperties": false  // Required for nested objects
        }
    },
    "required": ["title", "metadata"],
    "additionalProperties": false  // Auto-injected at root level
}))

推理努力（o1、o3 模型）

对于 OpenAI 推理模型，控制模型应用多少推理努力：

use adk_model::openai::{OpenAIClient, OpenAIConfig, ReasoningEffort};

let config = OpenAIConfig::new(&api_key, "o3-mini")
    .with_reasoning_effort(ReasoningEffort::High);
let model = OpenAIClient::new(config)?;

可用级别：Low、Medium、High。更高的努力会产生更彻底的推理，但会增加延迟和 token 消耗。

兼容 OpenAI 的本地 APIs

使用 OpenAIConfig::compatible() 连接到本地服务器（Ollama、vLLM、LM Studio）：

// Ollama exposes OpenAI-compatible API at /v1
let config = OpenAIConfig::compatible(
    "not-needed",                      // API key (ignored by Ollama)
    "http://localhost:11434/v1",       // Base URL
    "llama3.2"                         // Model name
);
let model = OpenAIClient::new(config)?;

注意：结构化输出（output_schema）需要后端支持。原生 OpenAI 完全支持它；本地服务器可能仅部分支持。

通过 OpenAI 兼容端点使用 Gemini

Gemini 模型可通过 OpenAI Chat Completions 线协议格式访问，地址为 https://generativelanguage.googleapis.com/v1beta/openai。使用 OpenAICompatibleConfig::gemini(...) 预设（位于 openai 功能下），并配合 GEMINI_API_KEY，即可通过与其他所有提供商相同的 OpenAI 兼容客户端运行 Gemini：

use adk_model::openai_compatible::{OpenAICompatible, OpenAICompatibleConfig};

let api_key = std::env::var("GEMINI_API_KEY")?;
let model = OpenAICompatible::new(
    OpenAICompatibleConfig::gemini(api_key, "gemini-3.5-flash"),
)?;

此路径支持聊天、流式传输、函数调用、结构化输出，以及 推理努力（OpenAI 的 reasoning_effort 映射到 Gemini 的思考 级别/预算）。Gemini 专属选项——例如带有 include_thoughts 的 thinking_config，或 cached_content——会通过请求的 extensions["openai"]["extra_body"]["google"] 映射传递，客户端会将其 按原样合并进请求体。

何时使用此方式而不是 GeminiModel：对于原生 Gemini 功能 （服务端工具、Interactions API、原生 ThinkingConfig、 以多模态为先的易用性），请优先选择 GeminiModel。当你希望在各提供商之间使用一个统一的客户端时，请使用 OpenAI 兼容预设。

示例（需要 GEMINI_API_KEY 或 GOOGLE_API_KEY）：

# Direct client: chat, reasoning effort, extra_body thinking, streaming,
# function calling, structured output.
cargo run -p adk-model --features openai --example gemini_openai_compat

# The same compat client driving a normal LlmAgent in a Runner.
# (Lives in adk-agent: it exercises the agent layer, which sits above adk-model.)
cargo run -p adk-agent --example gemini_openai_compat_agent

推理努力（o1、o3 模型）

使用 ReasoningEffort 控制模型应用多少推理努力：

use adk_model::openai::{OpenAIClient, OpenAIConfig, ReasoningEffort};

let config = OpenAIConfig::new(&api_key, "o3-mini")
    .with_reasoning_effort(ReasoningEffort::High);
let model = OpenAIClient::new(config)?;

可用级别：Low（最快）、Medium（均衡）、High（最全面）。

可用模型

示例输出

👤 User: Write a haiku about Rust programming

🤖 GPT-5: Memory so safe,
Ownership guards every byte—
Compiler, my friend.

---

Anthropic（Claude）🧠 智能

最适合：复杂推理、安全关键型应用、长文档

主要亮点：

• 🧠 出色的推理能力
• 🛡️ 最注重安全
• 📚 200K token 上下文
• ✍️ 优秀的写作质量

完整可运行示例

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    
    let api_key = std::env::var("ANTHROPIC_API_KEY")?;
    let model = AnthropicClient::new(AnthropicConfig::new(&api_key, "claude-sonnet-4-6"))?;

    let agent = LlmAgentBuilder::new("anthropic_assistant")
        .description("Anthropic-powered assistant")
        .instruction("You are a helpful assistant powered by Anthropic Claude. Be concise and thoughtful.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;
    Ok(())
}

可用模型

示例输出

👤 User: Explain quantum entanglement to a 10-year-old

🤖 Claude: Imagine you have two magic coins. When you flip them, they always 
land the same way - both heads or both tails - even if one coin is on Earth 
and the other is on the Moon! Scientists call this "entanglement." The coins 
are connected in a special way that we can't see, like invisible best friends 
who always make the same choice at the exact same time.

---

DeepSeek 💭 思考

最适合：复杂问题求解、数学、编码、推理任务

主要亮点：

• 💭 思考模式 - 显示思维链推理
• 💰 非常划算（比 GPT-4 便宜 10 倍）
• 🔄 针对重复前缀的上下文缓存
• 🧮 擅长数学和编码

完整可运行示例

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    
    let api_key = std::env::var("DEEPSEEK_API_KEY")?;
    
    // Standard chat model
    let model = DeepSeekClient::chat(&api_key)?;
    
    // OR: Reasoning model with thinking mode
    // let model = DeepSeekClient::reasoner(&api_key)?;

    let agent = LlmAgentBuilder::new("deepseek_assistant")
        .description("DeepSeek-powered assistant")
        .instruction("You are a helpful assistant powered by DeepSeek. Be concise.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;
    Ok(())
}

可用模型

示例输出（带思考模式的 Reasoner）

👤 User: What's 17 × 23?

🤖 DeepSeek: <thinking>
Let me break this down:
17 × 23 = 17 × (20 + 3)
       = 17 × 20 + 17 × 3
       = 340 + 51
       = 391
</thinking>

The answer is 391.

---

Groq ⚡ 超快

最适合：实时应用、聊天机器人、速度关键型任务

主要亮点：

• ⚡ 最快推理 - 比竞争对手快 10 倍
• 🔧 LPU（语言处理单元）技术
• 💰 有竞争力的定价
• 🦙 运行 LLaMA、Mixtral、Gemma 模型

完整可运行示例

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    
    let api_key = std::env::var("GROQ_API_KEY")?;
    let model = GroqClient::llama70b(&api_key)?;

    let agent = LlmAgentBuilder::new("groq_assistant")
        .description("Groq-powered assistant")
        .instruction("You are a helpful assistant powered by Groq. Be concise and fast.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;
    Ok(())
}

可用模型

示例输出

👤 User: Quick! Name 5 programming languages

🤖 Groq (in 0.2 seconds): 
1. Rust
2. Python
3. JavaScript
4. Go
5. TypeScript

---

切换提供方

所有提供方都实现相同的 Llm trait，因此切换很容易：

use adk_agent::LlmAgentBuilder;
use std::sync::Arc;

// Just change the model - everything else stays the same!
let model: Arc<dyn adk_core::Llm> = Arc::new(
    // Pick one:
    // GeminiModel::new(&api_key, "gemini-2.5-flash")?
    // OpenAIClient::new(OpenAIConfig::new(&api_key, "gpt-5-mini"))?
    // AnthropicClient::new(AnthropicConfig::new(&api_key, "claude-sonnet-4-6"))?
    // DeepSeekClient::chat(&api_key)?
    // GroqClient::llama70b(&api_key)?
);

let agent = LlmAgentBuilder::new("assistant")
    .instruction("You are a helpful assistant.")
    .model(model)
    .build()?;

---

示例

使用 cargo-adk 生成带有已验证 0.8 依赖项的特定提供方项目：

cargo adk new gemini_agent --provider gemini
cargo adk new openai_agent --template openai
cargo adk new anthropic_agent --provider anthropic

生成的项目会由 scripts/check-cargo-adk-templates.sh 在 CI 中编译。你可以在本站内嵌的 ADK-Rust Playground 中浏览并运行完整示例库。

---

相关内容

• Ollama (本地) - 使用 Ollama 在本地运行模型
• 本地模型 (mistral.rs) - 原生 Rust 推理
• LlmAgent - 在 agent 中使用模型
• Function Tools - 为 agent 添加工具

---

上一篇: ← 实时 Agent | 下一篇: Ollama (本地) →

当提供方无法承载内容时会发生什么

Content 可以表达的内容超过任何单一提供方传输所接受的范围，因此每个适配器都必须决定如何处理剩余部分。这些决定现在会被记录下来，而不是悄悄地应用。每一部分都会被分类：

降级和省略在记录时会发出 tracing 警告，注明部分类型、MIME 类型和原因，因此两者都不会悄无声息。

要在发送请求之前查看结果：

use adk_core::{Content, Part};
use adk_model::bedrock::convert::report_for_contents;

let content = Content {
    role: "user".to_string(),
    parts: vec![Part::inline_data("audio/wav", vec![0u8; 16])],
};
let report = report_for_contents(std::slice::from_ref(&content));

for omission in report.omitted_parts() {
    println!("{} was dropped: {}", omission.kind, omission.detail);
}

要拒绝一个会让模型接收到不完整内容的请求，而不是让模型去回答它从未见过的内容：

use adk_core::{Content, Part};
use adk_model::bedrock::convert::report_for_contents;

let content = Content {
    role: "user".to_string(),
    parts: vec![Part::inline_data("video/mp4", vec![0u8; 16])],
};

if let Some(error) = report_for_contents(std::slice::from_ref(&content)).into_error() {
    return Err(error);
}

into_error 只涵盖省略。降级仍然会到达模型，而拒绝它将拒绝文档中定义的文本回退。

注意： 该账本在构造上是完整的。任何离开适配器但没有记录归宿的部分——包括未来更改中新添加的部分——都会被记录为省略，并附带明确的“无记录原因”，且 adk-model/tests/part_conversion_matrix_tests.rs 会对此失败。

Bedrock Converse 覆盖范围