适用于 ADK 智能体的 OpenAI 模型¶
Experimental
openaimodel 包是实验性的，其行为可能会在未来发生变更或被移除。欢迎你提出
反馈！
你可以使用 OpenAI 模型配合 ADK。连接方式取决于你使用的编程语言：
- Go — 原生支持： ADK Go 提供了直接的
openaimodel包，实现了model.LLM接口，目标是 OpenAI Responses API 或 Chat Completions API。开始使用。 - Python — 通过 LiteLLM： ADK Python 通过 LiteLLM 连接器访问 OpenAI 模型（以及许多其他提供商）。参见 LiteLLM。
开始使用¶
openaimodel 包提供了一个用于与 OpenAI API 交互的客户端。它实现了 model.LLM 接口，默认使用 OpenAI Responses API，或者在 ClientConfig.API 选择时使用 Chat Completions API。
以下代码示例展示了在你的智能体中使用 OpenAI 模型的基本实现：
import (
"context"
"log"
"github.com/openai/openai-go/v3"
"google.golang.org/adk/v2/agent/llmagent"
"google.golang.org/adk/v2/model/openaimodel"
)
// 实例化模型
llm, err := openaimodel.NewModel(context.Background(), openai.ChatModelGPT4oMini, &openaimodel.ClientConfig{})
if err != nil {
log.Fatal(err)
}
// 创建智能体
agent, err := llmagent.New(llmagent.Config{
Name: "openai_agent",
Model: llm,
Instruction: "你是一个有用的 AI 助手。",
})
if err != nil {
log.Fatal(err)
}
如需完整可运行的示例，请参见 ADK Go 仓库中的 examples/openai/responses/。
需要 ADK Go v2.5.0 或更高版本。
import (
"context"
"log"
"os"
"github.com/openai/openai-go/v3"
"google.golang.org/adk/v2/agent/llmagent"
"google.golang.org/adk/v2/model/openaimodel"
)
// 在 Chat Completions API 上实例化模型
llm, err := openaimodel.NewModel(context.Background(), openai.ChatModelGPT4oMini, &openaimodel.ClientConfig{
APIKey: os.Getenv("OPENAI_API_KEY"),
API: openaimodel.APIChatCompletions,
})
if err != nil {
log.Fatal(err)
}
// 创建智能体
agent, err := llmagent.New(llmagent.Config{
Name: "openai_agent",
Model: llm,
Instruction: "你是一个有用的 AI 助手。",
})
if err != nil {
log.Fatal(err)
}
如需完整可运行的示例，请参见 ADK Go 仓库中的 examples/openai/completions/。
Chat Completions API¶
默认情况下，openaimodel 将请求发送到 OpenAI
Responses API
（POST /v1/responses）。几乎每个 OpenAI 兼容提供商都实现了
Chat Completions API
（POST /v1/chat/completions），而有些只实现了这一个。要使用它，请将
ClientConfig 的 API 字段设置为 openaimodel.APIChatCompletions，如
开始使用下的 Chat Completions API 标签页所示。智能体、工具和运行器在两种 API 下的工作方式相同。
为其他提供商设置 API 密钥
要访问其他 OpenAI 兼容提供商，请将 BaseURL 设置为其端点，
将 APIKey 设置为其密钥。当 APIKey 为空时，openai-go SDK 会
回退到 OPENAI_API_KEY 环境变量，并将该密钥发送到 BaseURL。
这两种 API 支持相同的功能，区别如下：
- 生成设置：
StopSequences、FrequencyPenalty、PresencePenalty和Seed会发送到 Chat Completions API。Responses API 没有对应的字段，并会为它们返回错误。 - 推理输出： Chat Completions API 不返回推理文本，因此响应中不包含思考部分，
ThinkingConfig.IncludeThoughts会被忽略。推理力度和推理 token 计数在两种 API 下都可用。 - 输出 token 上限：
MaxOutputTokens以max_completion_tokens形式发送。某些兼容服务器只认较旧的max_tokens字段，因此该限制在那里不会生效。
支持的功能¶
- 文本生成（流式和非流式）
- 函数（工具）调用
- 通过
OutputSchema实现结构化输出（JSON schema） - 推理模型（例如 o 系列），包括推理 token 计量
- Token logprobs
限制¶
- 仅支持文本 — 不支持多模态输入（图片、音频、文件）。
- 仅支持函数工具 — 不支持内置工具（Google 搜索、代码执行等）。
- 结构化输出使用 OpenAI 严格模式 — 在
OutputSchema中声明的每个字段都被视为必填。 - 部分
GenerateContentConfig选项会返回错误而非被静默忽略：TopK、多个候选、请求标签和安全设置。Responses API 还会拒绝停止序列、频率/存在惩罚和 seed，而 Chat Completions API 支持这些。
配置选项¶
ClientConfig 提供了多个用于配置客户端的选项：
APIKey：你的 OpenAI API 密钥。BaseURL：自定义端点 URL，适用于 OpenAI 兼容端点。HTTPClient：自定义*http.Client。Options：高级openai-go请求选项（[]option.RequestOption）。API：要调用的 OpenAI API：openaimodel.APIResponses（默认）或openaimodel.APIChatCompletions。参见 Chat Completions API。
如果 APIKey 或 BaseURL 留空，它们将自动回退到 OPENAI_API_KEY 和 OPENAI_BASE_URL 环境变量，由底层 openai-go SDK 的默认行为处理。
OpenAI 模型认证¶
使用 OpenAI 模型时，你必须提供 API 密钥来向 OpenAI API 进行认证。提供此信息最直接的方式是使用环境变量或 .env 文件。
openaimodel 包还支持 OpenAI 兼容端点（例如通过 Ollama、LM Studio 或 vLLM 提供的本地模型），只需配置基础 URL 即可。如果该端点不提供 Responses API，还需将 API 设置为 openaimodel.APIChatCompletions，如 Chat Completions API 中所述。
