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.0

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

示例:

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="You are a helpful assistant based on Llama 3, hosted on Vertex AI.",
    generate_content_config=types.GenerateContentConfig(max_output_tokens=2048),
    # ... 其他智能体参数
)

微调模型端点¶

Supported in ADKPython v0.2.0

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

示例:

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="You are a specialized assistant trained on specific data.",
    # ... 其他智能体参数
)

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="You are an assistant powered by Claude 3 Sonnet on Vertex AI.",
    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 文档中关于 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("You are an assistant powered by Claude 3 Sonnet on Vertex AI.")
            // .generateContentConfig(...) // 可选:如果需要,添加生成配置
            // ... 其他智能体参数
            .build();

        return agentClaudeVertexAi;
    }

    public static void main(String[] args) {
        try {
            LlmAgent agent = createAgent();
            System.out.println("Successfully created agent: " + agent.name());
            // 在这里你通常会设置 Runner 和 Session 来与智能体交互
        } catch (IOException e) {
            System.err.println("Failed to create agent: " + e.getMessage());
            e.printStackTrace();
        }
    }
}