企业官网建设流程全解析

Genkit Go 模型提供方接入全指南：Google AI、Vertex AI、Anthropic、OpenAI 兼容与 Ollama 实战

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

Genkit Go 是面向 Go 语言的 AI 开发 SDK，通过统一的ai接口屏蔽不同模型提供方的差异。本文以skills/cloud/genkit-go/references/providers.md为核心，系统讲解在 Genkit Go 中接入 Google AI（Gemini）、Vertex AI、Anthropic（Claude）、任意 OpenAI 兼容 API（OpenAI、DeepSeek、xAI 等）以及本地 Ollama 模型的完整流程，包括插件注册、环境变量配置、模型引用方式、提供方专属参数下发，以及多提供方共存的单实例注册模式。读完本文，你将能够在同一个 Go 应用中灵活切换、混用多个模型提供方，并为生产环境的故障转移（Fallback）与重试打下基础。

一、前置知识：Genkit Go 的插件与初始化模型

在深入各提供方之前，需要先理解 Genkit Go 的"插件 +genkit.Init"架构。所有模型提供方都是以插件形式存在的，它们在github.com/genkit-ai/genkit/go模块下的plugins/子包中发布，无需单独拉取模块，直接 import 后执行go mod tidy即可。可用插件包括（见 getting-started.md）：

• plugins/googlegenai：Google AI 与 Vertex AI
• plugins/anthropic：Anthropic Claude
• plugins/compat_oai：OpenAI 兼容 API（OpenAI、Groq、xAI 等）
• plugins/ollama：本地 Ollama 模型
• plugins/middleware：内置中间件包（Retry、Fallback、ToolApproval、Filesystem、Skills）

每个应用都从genkit.Init开始，它返回一个*Genkit实例g，作为全局资源注册中心：

ctx := context.Background() g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}))

genkit.Init支持若干初始化选项（详见 getting-started.md）：

• genkit.WithPlugins(...)：注册一个或多个插件
• genkit.WithDefaultModel("googleai/gemini-flash-latest")：设置默认模型，当调用未显式指定模型时使用
• genkit.WithPromptDir("my-prompts")：设置.prompt文件目录（默认prompts）
• genkit.WithPromptFS(promptsFS)：通过go:embed将.prompt文件嵌入二进制

需要特别强调的是，g必须显式传递到所有 Genkit 函数中（genkit.GenerateText(ctx, g, ...)），而不是存成全局变量，这是整个 SDK 的核心模式。下面各提供方的接入都建立在这个统一骨架之上。

二、Google AI（Gemini）：云端 Gemini 的直连接入

Google AI（ai.google.dev）是接入 Gemini 系列模型最直接的方式，适合快速开发和原型验证。

2.1 插件注册与凭据

import "github.com/genkit-ai/genkit/go/plugins/googlegenai" g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}))

环境变量：GEMINI_API_KEY或GOOGLE_API_KEY。Genkit 在初始化插件时读取环境变量获取 API Key，无需在代码中硬编码凭据。

2.2 模型命名规则

模型名遵循googleai/<model-id>格式，其中<model-id>与 Google AI 官方模型 ID 一致（如gemini-flash-latest、gemini-pro-latest）。由于模型 ID 更新频繁，官方建议查阅 ai.google.dev 的最新模型列表，而非硬编码旧 ID。

2.3 三种引用模型的方式

// 方式一：按名称字符串引用（最简单，适用于大多数场景） ai.WithModelName("googleai/gemini-flash-latest") // 方式二：ModelRef 携带提供方专属配置 // 这里通过 ThinkingConfig 将 thinking budget 设为 0，即关闭 Gemini 2.x 系列的思考模式 ai.WithModel(googlegenai.ModelRef("googleai/gemini-flash-latest", &genai.GenerateContentConfig{ ThinkingConfig: &genai.ThinkingConfig{ ThinkingBudget: genai.Ptrint32, // disable thinking }, })) // 方式三：直接查找模型实例 // 从已初始化的 *Genkit 实例中取回模型，可复用于多次调用 m := googlegenai.GoogleAIModel(g, "gemini-flash-latest")

三种方式对应三种使用场景：WithModelName用于快速指定；ModelRef用于需要在模型引用上固化提供方参数（如关闭思考模式、设定输出配置）的场景；GoogleAIModel用于需要把模型当作一等对象传递、复用的场景。三者可以配合genkit.GenerateText/genkit.Generate/genkit.GenerateData使用（相关 API 见 generation.md）。

三、Vertex AI：面向 Google Cloud 生产环境的 Gemini 接入

Vertex AI 是 Google Cloud 的托管 AI 平台，适合已有 GCP 项目、需要 IAM 权限治理与生产级 SLA 的场景。它与 Google AI 使用相同的模型 ID，但凭据体系完全不同。

3.1 插件注册与环境变量

import "github.com/genkit-ai/genkit/go/plugins/googlegenai" g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.VertexAI{}))

环境变量：GOOGLE_CLOUD_PROJECT（GCP 项目 ID）、GOOGLE_CLOUD_LOCATION或GOOGLE_CLOUD_REGION（区域，二者取一即可，如us-central1）。

凭据：Vertex AI 使用 Application Default Credentials（ADC）完成身份认证，典型流程是先在本地执行：

gcloud auth application-default login

之后 SDK 会自动读取 ADC 凭据，无需在代码或环境变量中管理 API Key，这与 Google AI 的 API Key 方式形成鲜明对比，也意味着代码在本地与 GCP 运行时（如 Cloud Run、GKE）之间可以无缝迁移。

3.2 模型引用

模型名遵循vertexai/<model-id>格式，模型 ID 与 Google AI 一致：

ai.WithModelName("vertexai/gemini-flash-latest")

从源码结构看，plugins/googlegenai同时承载GoogleAI{}与VertexAI{}两个插件结构，二者共用底层genai（Google Generative AI SDK）类型体系，因此ModelRef携带的genai.GenerateContentConfig配置对 Vertex AI 同样适用。

四、Anthropic（Claude）：接入 Anthropic 官方 SDK 类型

Genkit Go 的 Anthropic 插件直接基于anthropics/anthropic-sdk-go构建，因此提供方专属配置可以直接使用 Anthropic SDK 的强类型参数，无需做 map 转换。

4.1 插件注册与环境变量

import ( "github.com/anthropics/anthropic-sdk-go" // Anthropic SDK types ant "github.com/genkit-ai/genkit/go/plugins/anthropic" // Genkit plugin ) g := genkit.Init(ctx, genkit.WithPlugins(&ant.Anthropic{}))

环境变量：ANTHROPIC_API_KEY。

模型名遵循anthropic/<model-id>格式，如anthropic/claude-sonnet-4-6。最新模型 ID 需查阅 Anthropic 官方模型文档。

4.2 模型引用与提供方配置

// 按名称引用 ai.WithModelName("anthropic/claude-sonnet-4-6") // 携带 Anthropic SDK 类型的提供方配置（通过 ai.WithConfig 下发） ai.WithConfig(&anthropic.MessageNewParams{ Temperature: anthropic.Float(1.0), MaxTokens: *anthropic.IntPtr(2000), Thinking: anthropic.ThinkingConfigParamUnion{ OfEnabled: &anthropic.ThinkingConfigEnabledParam{ BudgetTokens: *anthropic.IntPtr(1024), }, }, })

这里体现了 Genkit 与 Google AI 插件的一个差异：googlegenai使用ModelRef的第二个参数携带配置，而anthropic通过ai.WithConfig传入 SDK 原生类型。Thinking配置开启了 Claude 的扩展思考（Extended Thinking）模式并分配 1024 token 的思考预算，适用于复杂推理任务；Temperature与MaxTokens则分别控制采样随机性与最大输出长度。关于ai.WithConfig更通用的用法（如ai.WithConfig(map[string]any{"temperature": 0.7})），可参考 generation.md 的 Common Options 一节。

五、OpenAI 兼容接入（compat_oai）：一套代码对接任意兼容 API

compat_oai插件可以对接任何 OpenAI 兼容的 Chat Completions API，包括 OpenAI 官方、DeepSeek、xAI（Grok）、Groq 等，是异构模型提供方统一接入的关键工具。

5.1 插件配置与注册

import "github.com/genkit-ai/genkit/go/plugins/compat_oai" openaiPlugin := &compat_oai.OpenAICompatible{ Provider: "openai", // 唯一标识符，用于区分多个兼容提供方 APIKey: os.Getenv("OPENAI_API_KEY"), // BaseURL: "https://custom-endpoint/v1", // 非 OpenAI 官方提供方需指定自定义端点 } g := genkit.Init(ctx, genkit.WithPlugins(openaiPlugin))

关键配置项说明：

• Provider：该提供方的唯一标识符，会参与模型名的构成，必须在同一应用中保持唯一；
• APIKey：API 密钥，通常从环境变量读取；
• BaseURL：自定义 API 端点。对接 OpenAI 官方时可不填（默认官方端点）；对接 DeepSeek、xAI 等第三方时必须指定其各自的/v1兼容端点，例如https://api.deepseek.com/v1。

5.2 显式定义模型

与 Google AI / Anthropic 插件不同，compat_oai不会自动发现模型，需要显式调用DefineModel定义，并将定义结果作为模型对象使用：

model := openaiPlugin.DefineModel("openai", "gpt-4o", compat_oai.ModelOptions{}) // 在生成调用中使用 ai.WithModel(model)

DefineModel的三个参数分别是 Provider 标识符、模型 ID 与ModelOptions。这意味着如果你同时对接 OpenAI 与 DeepSeek，需要分别创建两个OpenAICompatible插件实例（不同Provider标识符），并为每个实例定义自己的模型列表。

六、Ollama：本地模型接入

Ollama 插件用于接入本地运行的模型，适合离线环境、数据隐私敏感场景或成本控制需求。它同样采用"显式定义模型"的模式。

6.1 插件配置与注册

import "github.com/genkit-ai/genkit/go/plugins/ollama" ollamaPlugin := &ollama.Ollama{ ServerAddress: "http://localhost:11434", Timeout: 60, // seconds } g := genkit.Init(ctx, genkit.WithPlugins(ollamaPlugin))

配置项说明：

• ServerAddress：Ollama 服务地址，默认本机http://localhost:11434；若 Ollama 运行在远程主机或容器中，需相应修改；
• Timeout：请求超时时间，单位为秒。本地大模型推理耗时较长，需要合理设置避免过早超时。

6.2 定义本地模型

model := ollamaPlugin.DefineModel(g, ollama.ModelDefinition{ Name: "llama3.1", Type: "chat", // 或 "generate" }, nil, // 可选 *ModelOptions ) // 在生成调用中使用 ai.WithModel(model)

ModelDefinition的Name对应你在 Ollama 中ollama pull拉取的模型标签（如llama3.1、qwen2.5）；Type指定模型交互类型，chat适用于对话模型，generate适用于纯补全模型；第三个参数为可选的*ModelOptions，不使用时传nil。

七、多提供方共存：单实例多模型混用

Genkit Go 允许在同一个*Genkit实例中注册多个模型提供方，并在每次生成调用时按需选择模型，这是构建多云、多模型策略的基础能力。

7.1 注册多个插件并设置默认模型

g := genkit.Init(ctx, genkit.WithPlugins( &googlegenai.GoogleAI{}, &ant.Anthropic{}, ), genkit.WithDefaultModel("googleai/gemini-flash-latest"), )

WithDefaultModel指定的默认模型会在所有未显式指定模型的调用中生效，保证"开箱即用"。

7.2 每次调用选择不同模型

// 使用 Gemini text1, _ := genkit.GenerateText(ctx, g, ai.WithModelName("googleai/gemini-flash-latest"), ai.WithPrompt("Hello from Gemini"), ) // 使用 Claude text2, _ := genkit.GenerateText(ctx, g, ai.WithModelName("anthropic/claude-sonnet-4-6"), ai.WithPrompt("Hello from Claude"), )

由于每次调用的模型都是通过ai.WithModelName独立指定的，你可以在一个应用中实现诸如"摘要用 Gemini、代码生成用 Claude、路由决策用本地 Ollama"这样的混合策略。

7.3 与中间件联动：跨提供方 Fallback

多提供方注册的另一个典型价值是与内置中间件配合实现故障转移。plugins/middleware包中的Fallback中间件可以在主模型不可用时自动切换到备选模型，而Retry中间件则负责带退避的重试（详见 middleware.md）：

ai.WithUse(&middleware.Fallback{ Models: []ai.ModelRef{ googlegenai.ModelRef("googleai/gemini-flash-latest", nil), googlegenai.ModelRef("vertexai/gemini-flash-latest", nil), }, })

需要注意的是，Fallback中每个备选模型使用各自ModelRef携带的配置，不会继承原始请求的配置；且可以通过调整Retry与Fallback的嵌套顺序（Retry { Fallback { ... } }或反之）控制"先重试整个级联"还是"先重试主模型再切换"。这为多云高可用提供了现成的组合范式。

八、提供方选型速查与最佳实践

8.1 选型速查表

8.2 实践建议

1. 凭据统一走环境变量或 ADC：Google AI / Anthropic 读取环境变量，Vertex AI 走 ADC，避免在代码库中提交密钥。生产部署建议结合密钥管理服务注入环境变量。
2. 模型 ID 不要硬编码：模型 ID 更新频繁，建议查各提供方官方文档获取最新 ID，或用-latest后缀（如gemini-flash-latest）跟随更新。
3. 优先用g显式传参：始终把genkit.Init返回的*Genkit实例显式传入所有函数，避免全局变量带来的初始化时序问题。
4. 多提供方配合 Fallback 使用：将googleai/与vertexai/等配对配置为Fallback模型列表，实现同模型跨平台高可用。
5. 结合 CLI 验证：使用genkit start -- go run .启动应用即可在 Developer UI（默认http://localhost:4000）中运行 flow、打开模型 Playground 并查看每次调用的模型输入输出与 token 用量，是排查提供方配置问题的最快路径（详见 getting-started.md 与 SKILL.md）。

九、小结

本文基于skills/cloud/genkit-go/references/providers.md梳理了 Genkit Go 接入全部主流模型提供方的完整路径：Google AI 与 Vertex AI 共享plugins/googlegenai包与genai配置体系、Anthropic 插件直接消费官方 SDK 强类型、compat_oai以显式DefineModel方式打通任意 OpenAI 兼容端点、Ollama 提供本地推理能力。多提供方可在单个genkit.Init中并存，配合WithDefaultModel与Fallback/Retry中间件即可构建健壮的多模型应用。相关生成 API、中间件与 HTTP 部署细节可继续阅读同目录下的 generation.md、middleware.md 与 flows-and-http.md。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills