ADK 智能体的 Vertex AI 托管模型¶

对于企业级的可扩展性、可靠性以及与 Google Cloud 的 MLOps 生态系统的集成，你可以使用部署到 Vertex AI 端点的模型。这包括来自 Model Garden 的模型或你自己的微调模型。

集成方法： 将完整的 Vertex AI 端点资源字符串 (projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID) 直接传递给 LlmAgent 的 model 参数。

Vertex AI 设置¶

确保你的环境已配置为 Vertex AI:

身份验证： 使用应用程序默认凭据 (ADC):
```
gcloud auth application-default login
```

环境变量： 设置你的项目和位置：

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_VERTEX_AI_LOCATION" # 例如，us-central1

启用 Vertex 后端： 至关重要的是，确保 google-genai 库针对 Vertex AI:
```
export GOOGLE_GENAI_USE_VERTEXAI=TRUE
```

Model Garden 部署¶

Supported in ADKPython v0.2.0Java v0.1.0

你可以将来自 Vertex AI Model Garden 的各种开放和专有模型部署到端点。

示例：

PythonJava

from google.adk.agents import LlmAgent
from google.genai import types # 用于配置对象

# --- 使用从 Model Garden 部署的 Llama 3 模型的示例智能体 ---

# 替换为你实际的 Vertex AI 端点资源名称
llama3_endpoint = "projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_LLAMA3_ENDPOINT_ID"

agent_llama3_vertex = LlmAgent(
    model=llama3_endpoint,
    name="llama3_vertex_agent",
    instruction="你是一个基于 Llama 3 的得力助手，托管在 Vertex AI 上。",
    generate_content_config=types.GenerateContentConfig(max_output_tokens=2048),
    # ... 其他智能体参数
)

import com.google.adk.agents.LlmAgent;
import com.google.adk.models.Gemini;
import com.google.genai.types.GenerateContentConfig;

// ...

// 替换为你实际的 Vertex AI 端点资源名称
String llama3Endpoint = "projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_LLAMA3_ENDPOINT_ID";

LlmAgent agentLlama3Vertex = LlmAgent.builder()
    .model(Gemini.builder()
        .modelName(llama3Endpoint)
        .build())
    .name("llama3_vertex_agent")
    .instruction("你是一个基于 Llama 3 的得力助手，托管在 Vertex AI 上。")
    .generateContentConfig(GenerateContentConfig.builder()
        .maxOutputTokens(2048)
        .build())
    // ... 其他智能体参数
    .build();

微调模型端点¶

Supported in ADKPython v0.2.0Java v0.1.0

部署你的微调模型 (无论是基于 Gemini 还是 Vertex AI 支持的其他架构) 会生成一个可以直接使用的端点。

示例：

PythonJava

from google.adk.agents import LlmAgent

# --- 使用微调后的 Gemini 模型端点的示例智能体 ---

# 替换为你微调模型的端点资源名称
finetuned_gemini_endpoint = "projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_FINETUNED_ENDPOINT_ID"

agent_finetuned_gemini = LlmAgent(
    model=finetuned_gemini_endpoint,
    name="finetuned_gemini_agent",
    instruction="你是一个经过特定数据训练的专业助手。",
    # ... 其他智能体参数
)

import com.google.adk.agents.LlmAgent;
import com.google.adk.models.Gemini;

// ...

// 替换为你微调模型的端点资源名称
String finetunedGeminiEndpoint = "projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_FINETUNED_ENDPOINT_ID";

LlmAgent agentFinetunedGemini = LlmAgent.builder()
    .model(Gemini.builder()
        .modelName(finetunedGeminiEndpoint)
        .build())
    .name("finetuned_gemini_agent")
    .instruction("你是一个经过特定数据训练的专业助手。")
    // ... 其他智能体参数
    .build();

Vertex AI 上的 Anthropic Claude¶

Supported in ADKPython v0.2.0Java v0.1.0

一些提供商，如 Anthropic，直接通过 Vertex AI 提供他们的模型。

示例：

PythonJava

集成方法： 使用直接模型字符串 (例如，"claude-3-sonnet@20240229"),但需要在 ADK 内手动注册。

为什么需要注册？ ADK 的注册表会自动识别 gemini-* 字符串和标准 Vertex AI 端点字符串 (projects/.../endpoints/...),并通过 google-genai 库路由它们。对于直接通过 Vertex AI 使用的其他模型类型 (如 Claude),你必须明确告诉 ADK 注册表哪个特定的包装类 (在这种情况下是 Claude) 知道如何使用 Vertex AI 后端处理该模型标识符字符串。

设置：

Vertex AI 环境： 确保完成统一的 Vertex AI 设置 (ADC、环境变量、GOOGLE_GENAI_USE_VERTEXAI=TRUE)。
安装提供商库： 安装为 Vertex AI 配置的必要客户端库。
```
pip install "anthropic[vertex]"
```

注册模型类： 在应用程序开始附近添加此代码，在使用 Claude 模型字符串创建智能体之前：

# 通过 Vertex AI 与 LlmAgent 直接使用 Claude 模型字符串所需
from google.adk.models.anthropic_llm import Claude
from google.adk.models.registry import LLMRegistry

LLMRegistry.register(Claude)

from google.adk.agents import LlmAgent
from google.adk.models.anthropic_llm import Claude # 注册所需的导入
from google.adk.models.registry import LLMRegistry # 注册所需的导入
from google.genai import types

# --- 注册 Claude 类 (在启动时执行一次) ---
LLMRegistry.register(Claude)

# --- 在 Vertex AI 上使用 Claude 3 Sonnet 的示例智能体 ---

# Vertex AI 上 Claude 3 Sonnet 的标准模型名称
claude_model_vertexai = "claude-3-sonnet@20240229"

agent_claude_vertexai = LlmAgent(
    model=claude_model_vertexai, # 注册后传递直接字符串
    name="claude_vertexai_agent",
    instruction="你是一个由 Vertex AI 上的 Claude 3 Sonnet 驱动的助手。",
    generate_content_config=types.GenerateContentConfig(max_output_tokens=4096),
    # ... 其他智能体参数
)

集成方法： 直接实例化特定于提供商的模型类 (例如，com.google.adk.models.Claude) 并使用 Vertex AI 后端进行配置。

为什么需要直接实例化？ Java ADK 的 LlmRegistry 默认主要处理 Gemini 模型。对于 Vertex AI 上的第三方模型 (如 Claude),你需要直接向 LlmAgent 提供 ADK 包装类 (例如 Claude) 的实例。此包装类负责通过其特定的客户端库与模型交互，该库配置为 Vertex AI。

设置：

Vertex AI 环境：
- 确保你的 Google Cloud 项目和区域已正确设置。
- 应用程序默认凭据 (ADC): 确保 ADC 在你的环境中正确配置。这通常通过运行 gcloud auth application-default login 来完成。Java 客户端库使用这些凭据向 Vertex AI 进行身份验证。有关详细设置，请参阅 Google Cloud Java documentation on ADC。
提供商库依赖项：
- 第三方客户端库 (通常是传递性的): ADK 核心库通常包含 Vertex AI 上常见第三方模型所需的客户端库 (如 Anthropic 的所需类) 作为传递性依赖项。这意味着你可能不需要在你的 pom.xml 或 build.gradle 中明确添加 Anthropic Vertex SDK 的单独依赖项。
实例化和配置模型： 创建 LlmAgent 时，实例化 Claude 类 (或其他提供商的等效类) 并配置其 VertexBackend。

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.vertex.backends.VertexBackend;
import com.google.adk.agents.LlmAgent;
import com.google.adk.models.Claude; // ADK 的 Claude 包装器
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;

// ... 其他导入

public class ClaudeVertexAiAgent {

    public static LlmAgent createAgent() throws IOException {
        // Vertex AI 上 Claude 3 Sonnet 的模型名称 (或其他版本)
        String claudeModelVertexAi = "claude-3-7-sonnet"; // 或任何其他 Claude 模型

        // 使用 VertexBackend 配置 AnthropicOkHttpClient
        AnthropicClient anthropicClient = AnthropicOkHttpClient.builder()
            .backend(
                VertexBackend.builder()
                    .region("us-east5") // 指定你的 Vertex AI 区域
                    .project("your-gcp-project-id") // 指定你的 GCP 项目 ID
                    .googleCredentials(GoogleCredentials.getApplicationDefault())
                    .build())
            .build();

        // 使用 ADK Claude 包装器实例化 LlmAgent
        LlmAgent agentClaudeVertexAi = LlmAgent.builder()
            .model(new Claude(claudeModelVertexAi, anthropicClient)) // 传递 Claude 实例
            .name("claude_vertexai_agent")
            .instruction("你是一个由 Vertex AI 上的 Claude 3 Sonnet 驱动的助手。")
            // .generateContentConfig(...) // 可选：如果需要，添加生成配置
            // ... 其他智能体参数
            .build();

        return agentClaudeVertexAi;
    }

    public static void main(String[] args) {
        try {
            LlmAgent agent = createAgent();
            System.out.println("成功创建智能体：" + agent.name());
            // 在这里你通常会设置 Runner 和 Session 来与智能体交互
        } catch (IOException e) {
            System.err.println("创建智能体失败：" + e.getMessage());
            e.printStackTrace();
        }
    }
}

Vertex AI 上的开放模型¶

Supported in ADKPython v0.1.0Java v0.1.0

Vertex AI 通过模型即服务 (MaaS) 提供了精选的开源模型，例如 Meta Llama。这些模型通过托管 API 访问，允许你在不手动管理底层基础设施的情况下进行部署和扩展。有关可用选项的完整列表，请参阅 Vertex AI MaaS 上的开放模型文档。

Python

你可以使用 LiteLLM 库在 Vertex AI MaaS 上访问 Meta Llama 等开放模型。

集成方法： 使用 LiteLlm 包装类并将其设置为 LlmAgent 的 model 参数。请确保阅读了 ADK 智能体的 LiteLLM 模型连接器文档，了解如何在 ADK 中使用 LiteLLM 访问。

设置：

Vertex AI 环境： 确保完成统一的 Vertex AI 设置 (ADC、环境变量、GOOGLE_GENAI_USE_VERTEXAI=TRUE)。
安装 LiteLLM:
```
pip install litellm
```

示例：

from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm

# --- 使用 Meta Llama 4 Scout 的示例智能体 ---
agent_llama_vertexai = LlmAgent(
    model=LiteLlm(model="vertex_ai/meta/llama-4-scout-17b-16e-instruct-maas"), # LiteLLM 模型字符串格式
    name="llama4_agent",
    instruction="你是一个由 Llama 4 Scout 驱动的得力助手。",
    # ... 其他智能体参数
)