Gemini Provider¶

1. 定位¶

Gemini 是 Google 的双模式 Provider,支持 AI Studio(直接 API)和 Vertex AI(企业级 GCP).优势: - 超大 Context Window(2.5/2.0 系列 1M tokens;1.5 Pro 2M) - 极强的多模态能力(图像,视频帧) - Vertex AI 企业级安全和合规

2. 支持的模型¶

数据来源:core/pkg/providers/gemini/provider.go 静态表(2026-04,AI Studio 定价).

模型	Context Window	Max Output	Input $/1M	Output $/1M	Thinking	Caching	备注
gemini-2.5-pro	1M	64K	$1.25	$10	✓	✓	旗舰,≤200K input 享低价
gemini-2.5-flash	1M	64K	$0.15	$0.60	✓	✓	高性价比
gemini-2.5-flash-thinking-exp	1M	64K	$0.15	$0.60	✓	✗(实验)	实验思考模型
gemini-2.0-flash	1M	8K	$0.10	$0.40	✗	✓	极致便宜
gemini-2.0-flash-thinking-exp	1M	8K	$0.10	$0.40	✓	✗(实验)	实验思考模型
gemini-1.5-pro	2M	8K	$1.25	$5	✗	✓	长上下文
gemini-1.5-flash	1M	8K	$0.075	$0.30	✗	✓	稳定版
gemini-1.5-flash-8b	1M	8K	$0.0375	$0.15	✗	✓	最便宜

所有模型均支持 Vision(图像 / 视频帧).Vertex AI 路径定价可能不同,请以 GCP 控制台为准.

3. 配置示例¶

AI Studio 模式(默认)¶

import "git.flytoex.net/yuanwei/git.flytoex.net/yuanwei/flyto-agent/pkg/providers/gemini"

p := gemini.New(gemini.Config{
    APIKey:         os.Getenv("GEMINI_API_KEY"),
    BaseURL:        "https://generativelanguage.googleapis.com",
    ThinkingBudget:  8000,  // Extended thinking token 上限
})

Vertex AI 模式¶

p := gemini.New(gemini.Config{
    BearerToken:    os.Getenv("GCP_ACCESS_TOKEN"),
    BaseURL:        "https://us-central1-aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1/publishers/google/models",
    ThinkingBudget:  8000,
    Timeout:        60 * time.Second,  // 可选,ResponseHeaderTimeout (见 §3.1)
})

3.1 Timeout (P1 契约加固, 2026-04-13)¶

Config.Timeout 通过 http.Transport.ResponseHeaderTimeout 实现, 约束"从请求发出到收到响应首字节"的时间, 不影响 SSE 流式响应的后续 body 读取.Gemini 长回复和 Thinking 模式不受影响.

场景	Config 字段	行为
默认 (都不设)	`HTTPClient=nil, Timeout=0`	使用 `defaultTimeout=60s`
显式 Timeout	`HTTPClient=nil, Timeout=Xs`	使用 `Xs`
自定义 client	`HTTPClient=&http.Client{...}`	完全交给消费者, `Timeout` 被忽略

Gemini 特殊考虑: Vertex AI 通过 GCP 路由层,某些情况可能比 AI Studio 直连延迟稍高.如果在高延迟区域部署,可以把 Timeout 调到 90-120s 给路由层充足余量.详见 anthropic.md §3.1 完整论证.

4. 认证方式¶

AI Studio: ?key=<API_KEY> Query 参数

Vertex AI: Authorization: Bearer <GCP_TOKEN> Header

API Key 获取: Google AI Studio

5. 能力矩阵¶

能力	支持	备注
Streaming	✓	SSE 格式(每 chunk 是完整 `GenerateContentResponse`)
Tool Use	✓	Function calling
Extended Thinking	✓(仅 2.5 系列 + thinking-exp 模型)	`ThinkingBudget > 0`,未知模型保守不注入
Vision	✓	全模型支持(图像,视频帧)
JSON Mode	✓	`responseSchema`
Caching	✓(除两款 -exp 实验模型外)	Provider 不主动注入 cache 标记,由模型自动
Batch API	✗	Provider 未实现

6. 已知 quirks¶

Dual-Mode 设计¶

Provider 自动检测配置: - BearerToken 非空 → Vertex AI 模式 - APIKey 非空 → AI Studio 模式

ThinkingBudget 自动管理¶

如果模型不支持 thinking,自动禁用(不报错)
如果未设置但 NeedsThinking=true,默认 8000

SSE 格式特殊¶

Gemini 的 SSE 响应中每个 chunk 是完整的 GenerateContentResponse,thinking 内容通过 thought: true 标记.

Schema 适配¶

Gemini 的 JSON Schema 支持与 OpenAI 不同,实现会自动适配.

7. 错误处理¶

状态码	含义	处理建议
400	请求格式错误	检查 JSON payload
403	认证失败	检查 API Key 或 Token
429	速率限制	等待后重试
500	服务错误	等待后重试

8. 成本估算示例¶

Gemini 2.0 Flash 处理长文档(50000 input,1000 output):

Input:  50000 tokens × $0.10/1M  = $0.005
Output:  1000 tokens × $0.40/1M  = $0.0004
Total:                            ≈ $0.0054

对比 GPT-4o 相同输入:

Input:  50000 tokens × $2.5/1M  = $0.125
Output:  1000 tokens × $10/1M   = $0.01
Total:                            ≈ $0.135

Gemini 便宜 25 倍(长文本场景).

9. 数据驱动能力(Capabilities)¶

参见 docs/architecture/data-driven-capabilities-rfc.md 了解整体机制.PR2.4(2026-04)落地.

本 provider 的能力决策来自 req.Capabilities(engine 从 ModelRegistry 注入).包内静态表/const 降级为兜底.

本 provider 的决策路径:

路径	helper	兜底策略
`MaxTools` + `Exhaustive`	`resolveMaxTools`	`geminiMaxTools = 0`(Gemini 官方文档无显式上限,兜底跳过检查)
`SupportsThinking`	`resolveThinkingSupport`	`modelSupportsThinking(model)` 扫 `geminiModels` 静态表(2.5 / flash-thinking-exp 返回 true)
`SupportsCaching`	不使用	Gemini wire 层不处理 cache_control,`Config` 无 `EnableCaching`

gemini 最大的 silent disable 陷阱:早期方案 Stream() 有一处教科书级的静默清零:

if thinkingBudget > 0 && !modelSupportsThinking(req.Model) {
    thinkingBudget = 0  // silent disable
}

用户设了 ThinkingBudget=8000 但模型是 gemini-2.0-flash(不支持 thinking),budget 被静默清零.PR2.4 保留清零行为(零回归),但在 detectFeatureWarnings 里检测这个场景,emit WarningEvent{Code:"feature_unsupported"} 把 silent 转 loud.

双开关协议(want × can):Config.ThinkingBudget > 0 或 req.NeedsThinking=true 是用户 want 信号;registry SupportsThinking 或静态表是 can 信号.want=true can=false → warning 在流开头发送.