GeminiDesk - Google Gemini 实现指南¶

✨ 推荐说明¶

为什么选择 GeminiDesk？

在 DeskLLM 模式（纯文本生成）中，GeminiDesk 是多模态任务的首选方案：

与其他实现的对比¶

特性	GeminiDesk	ClaudeDesk	GPTDesk
多模态支持	✅ 原生支持	❌ 纯文本	⚠️ 有限支持
国内访问	✅ 相对稳定	❌ 困难	❌ 困难
Completion API	✅ 完善支持	❌ 支持很差	❌ 支持很差
长上下文	✅ 1M tokens	200K	128K
代理支持	✅ HTTP + SOCKS5	❌ 仅 HTTP	❌ 仅 HTTP
测试覆盖	✅ 充分测试	⚠️ 未充分测试	⚠️ 有限测试

核心优势¶

Completion API 支持完善
GPT 和 Claude 的 Completion API 在国内支持很差，或模型本身支持就有限
Gemini 的 Completion API 专门优化，功能完善
多模态原生支持
图片、视频、音频输入
无需降级处理，直接解析多模态内容
超长上下文窗口
Gemini 3: 1M tokens
Gemini 2.0 Flash: 1M tokens
适合大型文档和代码库分析
国内访问相对稳定
相比 Claude 和 GPT，Gemini API 在国内访问更稳定
支持 SOCKS5 代理，网络配置灵活
经过充分测试
TFRobot 团队对 GeminiDesk 进行了充分测试
生产环境验证，稳定性有保障

💡 推荐场景： - ✅ 多模态 Desk 模式：首选 GeminiDesk - ✅ 超长文档分析：1M 上下文优势 - ✅ 国内环境部署：网络访问稳定 - ✅ 需要 SOCKS5 代理：完整代理支持

概述¶

GeminiDesk 是基于 Google Gemini API 的 DeskLLM 实现，提供纯文本生成能力。Gemini 系列模型以多模态支持和长上下文窗口而著称，同时支持 SOCKS5 代理。

模型支持¶

快速开始¶

基本使用¶

from tfrobot.brain.chain.llms.generation_llms.desk_llm.gemini_desk import GeminiDesk
from tfrobot.brain.chain.prompt.memo_prompt import MemoPrompt
from tfrobot.schema.message.conversation.message_dto import TextMessage

# 创建 GeminiDesk 实例
desk_llm = GeminiDesk(
    name="gemini-2.5-flash",
    gemini_api_key="your_api_key"
)

# 配置系统提示
desk_llm.system_prompt = [
    MemoPrompt(template="你是一个专业的代码助手，擅长 Python 开发。")
]

# 调用
result = desk_llm.complete(
    current_input=TextMessage(content="帮我写一个快速排序函数")
)
print(result.generations[0].text)

配置 API 密钥¶

通过环境变量配置（推荐）：

export GOOGLE_GEMINI_API_KEY="your_api_key"

或直接传入：

desk_llm = GeminiDesk(
    name="gemini-2.5-flash",
    gemini_api_key="your_api_key"
)

核心参数¶

模型参数¶

参数	类型	默认值	说明
`name`	`str`	`gemini-2.5-flash`	模型名称
`max_tokens`	`int`	-	最大生成 tokens 数（max_output_tokens）
`temperature`	`float`	`0.7`	采样温度（0-2）
`top_p`	`float`	`1.0`	核采样参数
`top_k`	`int`	`40`	Top-K 采样参数
`stop_sequences`	`list[str]`	-	停止词列表
`stream`	`bool`	`False`	是否流式输出
`timeout`	`int`	`180`	请求超时时间（秒）
`context_window`	`int`	`128000`	上下文窗口大小

网络配置¶

参数	类型	默认值	说明
`gemini_api_key`	`str`	环境变量	Gemini API 密钥
`base_url`	`str`	`https://generativelanguage.googleapis.com/v1beta`	API 基础 URL
`proxy_host`	`str`	-	代理地址
`proxy_port`	`int`	-	代理端口
`proxy_user`	`str`	-	代理用户名
`proxy_pass`	`str`	-	代理密码
`socks5_proxy`	`bool`	`False`	是否使用 SOCKS5 代理

特殊功能¶

多模态支持¶

GeminiDesk 支持图片输入：

from tfrobot.brain.chain.llms.generation_llms.desk_llm.gemini_desk import GeminiDesk
from tfrobot.schema.message.conversation.message_dto import MultiPartMessage
from tfrobot.schema.message.msg_part import TextPart, ImagePart
from tfrobot.schema.message.image_url import ImgUrl

desk_llm = GeminiDesk(name="gemini-2.5-flash")

# 多模态输入
msg = MultiPartMessage(content=[
    TextPart(text="请描述这个界面的布局"),
    ImagePart(
        image_url=ImgUrl(url="screenshot.png")
    ),
])

result = desk_llm.complete(current_input=msg)
print(result.generations[0].text)

超长上下文窗口¶

Gemini 支持长达 1M-2M tokens 的上下文窗口：

desk_llm = GeminiDesk(
    name="gemini-2.5-flash",
    context_window=1_000_000  # 1M tokens
)

# 可以处理整个代码库或长文档
large_document = load_very_large_file()
desk_llm.original_desk_screenshot_prompt = [
    MemoPrompt(template=f"文档内容：\n{large_document}")
]

使用场景¶

代码生成¶

desk_llm = GeminiDesk(name="gemini-2.5-flash")

desk_llm.system_prompt = [
    MemoPrompt(template="你是一个 Python 专家，编写高质量、有文档的代码。")
]

desk_llm.purpose_prompt = [
    MemoPrompt(template="创建一个 Person 数据类，包含 name 和 age 属性。")
]

desk_llm.prefix_prompt = [
    MemoPrompt(template="```python\nfrom dataclasses import dataclass\n\n")
]

result = desk_llm.complete(current_input=TextMessage(content="开始生成"))
print(result.generations[0].text)

图像理解¶

desk_llm = GeminiDesk(name="gemini-2.0-flash")

desk_llm.system_prompt = [
    MemoPrompt(template="你是一个图像分析专家。")
]

msg = MultiPartMessage(content=[
    TextPart(text="请详细描述这张图片中的内容和布局"),
    ImagePart(
        image_url=ImgUrl(url="path/to/image.jpg", detail="high")
    ),
])

result = desk_llm.complete(current_input=msg)
print(result.generations[0].text)

长文档处理¶

desk_llm = GeminiDesk(
    name="gemini-2.5-flash",
    context_window=1_000_000
)

# 处理大型代码库
codebase = load_entire_codebase()

desk_llm.original_desk_screenshot_prompt = [
    MemoPrompt(template=f"代码库内容：\n{codebase}")
]

desk_llm.purpose_prompt = [
    MemoPrompt(template="请分析这个代码库的架构，并列出主要模块和它们的功能。")
]

result = desk_llm.complete(current_input=TextMessage(content="开始分析"))

代理配置¶

HTTP(S) 代理¶

desk_llm = GeminiDesk(
    name="gemini-2.5-flash",
    proxy_host="127.0.0.1",
    proxy_port=7890,
    socks5_proxy=False  # 默认使用 HTTP(S)
)

SOCKS5 代理¶

desk_llm = GeminiDesk(
    name="gemini-2.5-flash",
    socks5_proxy=True,
    proxy_host="127.0.0.1",
    proxy_port=1080
)

带认证的 SOCKS5 代理¶

desk_llm = GeminiDesk(
    name="gemini-2.5-flash",
    socks5_proxy=True,
    proxy_host="proxy.company.com",
    proxy_port=1080,
    proxy_user="username",
    proxy_pass="password"
)

错误处理¶

上下文超长¶

GeminiDesk 会自动检测并处理上下文超长错误：

from tfrobot.schema.exceptions import ContextTooLargeError

try:
    result = desk_llm.complete(current_input=very_long_input)
except ContextTooLargeError as e:
    print(f"目标大小: {e.target_size} tokens")
    print(f"模型: {e.model_name}")
    # 注意：Gemini 通常不返回 current_size
    # 由 Chain 层自动处理上下文压缩

API 格式变更处理¶

Gemini API 经常变更，GeminiDesk 使用多个正则模式匹配错误：

# 自动匹配多种错误格式
# 1. "maximum number of tokens allowed (N)"
# 2. "exceeds N tokens"
# 3. "token count...N"

高级用法¶

多轮编辑¶

from tfrobot.brain.chain.llms.generation_llms.desk_llm.gemini_desk import GeminiDesk

desk_llm = GeminiDesk(name="gemini-2.5-flash")

# 初始代码
original_code = """
def add(a, b):
    return a + b
"""

desk_llm.original_desk_screenshot_prompt = [
    MemoPrompt(template=f"原始代码：\n```python\n{original_code}\n```")
]

# 第一轮：添加类型注解
desk_llm.purpose_prompt = [
    MemoPrompt(template="添加类型注解。")
]

result1 = desk_llm.complete(current_input=TextMessage(content="开始编辑"))
current_code = result1.generations[0].text

# 第二轮：添加文档字符串
desk_llm.current_desk_screenshot_prompt = [
    MemoPrompt(template=f"当前代码：\n```python\n{current_code}\n```")
]

desk_llm.intermediate_prompt = [
    MemoPrompt(template="已添加类型注解。")
]

desk_llm.purpose_prompt = [
    MemoPrompt(template="添加文档字符串。")
]

result2 = desk_llm.complete(current_input=TextMessage(content="继续编辑"))
print(result2.generations[0].text)

多模态对话¶

desk_llm = GeminiDesk(name="gemini-2.0-flash")

# 第一轮：文本输入
msg1 = TextMessage(content="你好，我是你的助手")
result1 = desk_llm.complete(current_input=msg1)

# 第二轮：图片 + 文本
msg2 = MultiPartMessage(content=[
    TextPart(text="请帮我分析这张图片"),
    ImagePart(image_url=ImgUrl(url="image.png"))
])

result2 = desk_llm.complete(
    current_input=msg2,
    conversation=[msg1]  # 传入历史对话
)

最佳实践¶

1. 选择合适的模型¶

# 💡 GeminiDesk 是多模态 Desk 模式的首选方案
# 相比 ClaudeDesk 和 GPTDesk，具有更好的 Completion API 支持和国内访问稳定性

# 2025年最新推荐：

# 快速响应 + 高性价比（大多数场景）
desk_llm = GeminiDesk(name="gemini-2.0-flash")  # ¥0.72/M，价格极低

# 混合推理 + 复杂任务（旗舰级）
desk_llm = GeminiDesk(name="gemini-3-pro-preview")  # 1M 上下文，思考预算

# 超长上下文（2M tokens）
desk_llm = GeminiDesk(name="gemini-1.5-pro")  # 处理超大文档

# 平衡性能与速度
desk_llm = GeminiDesk(name="gemini-2.5-flash")

2. 利用超长上下文窗口¶

# Gemini 支持 1M-2M tokens 的上下文
desk_llm = GeminiDesk(
    name="gemini-2.5-flash",
    context_window=1_000_000
)

# 可以处理整个代码库
codebase = load_entire_codebase()

3. 合理设置采样参数¶

# 对于代码生成，使用低温度和高 Top-K
desk_llm = GeminiDesk(
    name="gemini-2.5-flash",
    temperature=0.2,
    top_k=40
)

4. 使用 SOCKS5 代理¶

# 在需要 SOCKS5 代理的环境中
desk_llm = GeminiDesk(
    name="gemini-2.5-flash",
    socks5_proxy=True,
    proxy_host="127.0.0.1",
    proxy_port=1080
)

性能优化¶

1. 减少 Prompt 长度¶

# 避免冗长的 Prompt
desk_llm.system_prompt = [
    MemoPrompt(template="你是 Python 专家。")  # 简洁明了
]

2. 使用合适的图片细节¶

# 低细节：更快，更少 tokens
ImagePart(image_url=ImgUrl(url="image.jpg", detail="low"))

# 高细节：更准确，更多 tokens
ImagePart(image_url=ImgUrl(url="image.jpg", detail="high"))

# 自动：平衡
ImagePart(image_url=ImgUrl(url="image.jpg", detail="auto"))

3. 异步调用¶

import asyncio

async def generate():
    desk_llm = GeminiDesk(name="gemini-2.5-flash")
    result = await desk_llm.async_complete(
        current_input=TextMessage(content="生成代码")
    )
    return result.generations[0].text

result = asyncio.run(generate())

API 版本说明¶

GeminiDesk 已升级至 google-genai>=1.39.1，使用新的数据结构：

旧版 API（已弃用）¶

# 旧版 API（不再使用）
from google import generativeai as genai

genai.configure(api_key="your_key")
model = genai.GenerativeModel('gemini-pro')

新版 API（当前使用）¶

# 新版 API（GeminiDesk 使用）
from google.genai import types
from google.genai.client import Client

client = Client(api_key="your_key")
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=["Your prompt here"]
)

与其他实现的区别¶

特性	GeminiDesk	ClaudeDesk	GPTDesk
多模态支持	✅ 强	❌	⚠️ 有限
上下文窗口	1M-2M	200K	128K
SOCKS5 代理	✅	❌	❌
API 稳定性	中	高	高
中文能力	中	中	中

已知问题¶

1. API 格式不稳定¶

Gemini API 经常变更，错误消息格式可能变化。GeminiDesk 使用多个正则模式匹配，但如果 API 再次变更，可能需要更新 _extract_context_size_from_error 方法。

2. Token 信息不完整¶

Gemini API 通常不返回当前 token 数量（current_size），只提供最大限制（target_size）。

3. 流式输出尚未实现¶

# 会抛出 NotImplementedError
desk_llm = GeminiDesk(stream=True)
result = desk_llm.complete(...)

模型名称	上下文窗口	特点	价格（输入）	发布时间
最新旗舰
`gemini-3-pro-preview`	1M	混合推理，思考预算	¥14.4-28.8/M	2025.01
`gemini-3-flash-preview`	1M	高性价比，快速响应	¥3.6/M	2025.01
主力推荐
`gemini-2.0-flash`	1M	多模态能力强，价格极低	¥0.72/M	2025.02
`gemini-2.5-flash`	1M	平衡性能与速度	-	2024
`gemini-2.5-pro`	1M	高质量推理	-	2024
经典系列
`gemini-1.5-pro`	2M	超长上下文窗口	-	2024