如何接入 Gemini 到 WorkBuddy

如何接入 Gemini 到 WorkBuddy

Gemini 是 Google 推出的多模态大模型系列，Gemini 2.5 Pro 支持 1M tokens 超长上下文与原生多模态理解（文本/图像/音频/视频），Gemini 2.5 Flash 则以低延迟、低价格覆盖高频任务。本教程教你把 Gemini 接入腾讯推出的桌面端 AI 助手 WorkBuddy（域名 workbuddy.qq.com），在桌面 GUI 中直接使用 Gemini 帮你写代码、做推理。

Gemini 接入 WorkBuddy 有两种方式，选一种就行：

前置准备

不管选哪种方式，都需要这几样东西：

• 操作系统为 Windows 10 20H2+ 或 macOS 12+
• 已注册 Google AI Studio 账号（用 Google 账号登录即可）
• 电脑能上网（国内访问 Gemini 需梯子，建议全局模式）
• 已从 workbuddy.qq.com 下载安装 WorkBuddy 桌面端

步骤一：获取 Gemini API Key

两种方式都要先领一张 Gemini 的「通行证」（API Key）。

1.1 注册并登录

1. 访问 Google AI Studio，使用 Google 账号登录
2. 免费层有每日额度可用，正式生产需绑定 Google Cloud 计费账号

1.2 创建 API Key

1. 登录后进入 API Keys 页面
2. 点击 「Create API key」 按钮
3. 选择一个 Google Cloud 项目（或新建默认项目）
4. 页面会显示一串以 AIza 开头的长字符串，这就是你的通行证

1.3 了解可用模型

注：2.5 Pro 在提示超过 200K tokens 时输入涨至 $2.50/M、输出涨至 $15.00/M；Flash 系列无论长度均保持平价。

步骤二：安装 WorkBuddy

如果你还没装 WorkBuddy 桌面端，先装上。

1. 下载客户端

1. 访问 workbuddy.qq.com，点击首页「下载客户端」
2. 根据系统选择 Windows 版 或 macOS 版安装包

2. 安装并登录

1. 双击安装包按提示完成安装
2. 启动 WorkBuddy，使用微信或 QQ 账号登录

步骤三：接入 Gemini

从这里开始，方式 A 和方式 B 分开走，选一种跟着做即可。

方式 A：应用端交互接入（推荐新手）

在 WorkBuddy 桌面端的设置界面里点选 + 填写，全程不用手写配置。

A1. 打开设置

启动 WorkBuddy，点击主界面右上角的齿轮（设置）图标。

A2. 进入模型配置

在设置窗口左侧选择 「模型配置」（或「供应商」）标签。

A3. 添加自定义供应商

点击 「添加自定义供应商」 或 「+ 新增」 按钮。

A4. 填写供应商信息

按提示依次填入：

1. 供应商名称：填 Gemini（仅作显示用，可自定义）
2. 协议类型：选 OpenAI-compatible（Gemini 提供 OpenAI 兼容端点）
3. API Base URL：填

A5. 粘贴 Gemini API Key

在 「API Key」 输入框里，把步骤一领到的 AIza 开头的通行证粘进去。

A6. 选择模型

在模型列表中添加你想用的模型 ID，例如：

可继续添加 gemini-2.5-pro 备用（复杂任务时切换）。

A7. 测试连接并保存

1. 点击 「测试连接」 按钮，出现「连接成功」字样即说明接通了
2. 点击 「保存」 完成配置

方式 B：配置文件手动接入（进阶）

如果你更喜欢直接改配置文件，可以跳过界面，手动编辑。

B1. 找到配置文件路径

WorkBuddy 的配置文件位置因系统而异：

• macOS：~/.workbuddy/config.json
• Windows：%APPDATA%\WorkBuddy\config.json

B2. 备份配置文件

修改前先复制一份 config.json 作为备份，避免改错导致 WorkBuddy 启动异常。

B3. 编写 Gemini 模型配置

打开 config.json，推荐用环境变量方式（最安全，避免 Key 明文写入）：

1{
2  "models": [
3    {
4      "name": "gemini-2.5-flash",
5      "provider": "openai-compatible",
6      "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai/",
7      "apiKeyEnv": "GEMINI_API_KEY",
8      "maxTokens": 4096,
9      "temperature": 0.7
10    },
11    {
12      "name": "gemini-2.5-pro",
13      "provider": "openai-compatible",
14      "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai/",
15      "apiKeyEnv": "GEMINI_API_KEY",
16      "maxTokens": 8192,
17      "temperature": 0.7
18    }
19  ],
20  "defaultModel": "gemini-2.5-flash"
21}

然后设置环境变量：

1# PowerShell（临时，当前会话有效）
2$env:GEMINI_API_KEY = "AIza你的实际Key"
3
4# 或设为系统永久环境变量（重启终端仍有效）
5[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "AIza你的实际Key", "User")

1# macOS / Linux（临时）
2export GEMINI_API_KEY="AIza你的实际Key"
3
4# 写入 ~/.zshrc 永久生效
5echo 'export GEMINI_API_KEY="AIza你的实际Key"' >> ~/.zshrc
6source ~/.zshrc

B4. 关键参数说明

B5. 重启 WorkBuddy

完全退出 WorkBuddy（不是最小化）后重新启动，让它加载新的配置文件。

步骤四：测试验证

4.1 选择 Gemini 模型

在 WorkBuddy 主聊天界面顶部的模型下拉框中，选择刚配置的 gemini-2.5-flash（方式 A 已自动列出，方式 B 需确认重启后已加载）。

4.2 发送测试消息

在聊天输入框发送一条测试消息：

如果收到来自 Gemini 的回复（通常会自报为 Gemini，由 Google 创建），恭喜你——接入成功！🎉

4.3 Python 快速验证（可选）

绕过 WorkBuddy 直接验证 API Key 是否有效：

1from openai import OpenAI
2
3client = OpenAI(
4    api_key="你的Gemini API Key",   # 替换为实际 Key（AIza 开头）
5    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
6)
7
8response = client.chat.completions.create(
9    model="gemini-2.5-flash",
10    messages=[
11        {"role": "system", "content": "你是一个有用的 AI 助手。"},
12        {"role": "user", "content": "说一句'Hello, Gemini!'"}
13    ],
14    max_tokens=100
15)
16
17print("✅ 连接成功！模型回复：")
18print(response.choices[0].message.content)

运行前确保已安装依赖并开启梯子：

1pip install openai
2python test_gemini.py

场景应用示例

🧩 场景 1：智能编程助手

将 gemini-2.5-flash 设为默认模型，在 WorkBuddy 中描述需求：

使用示例：

1请帮我用 Python 写一个读取 CSV 文件并计算每列均值的函数，
2要求处理缺失值并加上类型注解。

效果：

• 生成完整可运行的函数代码
• 自动添加参数说明、类型注解与边界处理
• 解释关键逻辑并提供调用示例

🧩 场景 2：长文档/整库代码分析

切换到 gemini-2.5-pro 模型，利用 1M 上下文窗口：

使用示例：

1请分析这个项目的整体架构，梳理各模块依赖关系，
2并指出潜在的耦合问题：
3[粘贴整个项目的核心代码文件]

效果：

• 单次处理数十万字的论文、合同、报告
• 整个中型代码库的全局分析与重构建议
• 注意单次请求尽量控制在 200K tokens 内，避免触发长上下文溢价

🧩 场景 3：多模态理解

利用 Gemini 原生多模态能力，输入图像让其分析：

使用示例：

1请识别这张架构图中的所有组件，并解释它们之间的数据流向。
2[附带图片]

效果：

• 识别图表、UI 截图、白板草图中的结构信息
• 提取图片中的文字与表格
• 适用于需求评审、文档数字化场景

最佳实践

💰 成本优化技巧

1. 优先用 Flash：日常对话、代码生成用 gemini-2.5-flash，比 Pro 便宜约 4 倍，仅在复杂推理时切 Pro

2. 控制上下文长度：2.5 Pro 在请求超过 200K tokens 时输入翻倍（$2.50/M）、输出涨至 $15.00/M，长文档建议分段或用 Flash

3. 利用上下文缓存：重复的长 system prompt 可启用 context cache，缓存读取仅约 $0.125/M

4. 使用 Batch API：非实时任务用批量接口，可享 50% 折扣

🔒 安全建议

1. 永远不要将 API Key 提交到 Git 仓库 —— 确保 .gitignore 包含 .env 和 config.json
2. 定期轮换 Key —— 在 Google AI Studio 定期重新生成密钥
3. 设置用量告警 —— 在 Google Cloud 控制台设置预算上限，防止意外超额
4. 使用最小权限原则 —— 仅授予必要的 API 权限范围

🐛 故障排查速查表

扩展与进阶

📚 更多学习资源

🚀 进阶玩法

• 多模型混合部署：在 config.json 中同时配置 Gemini + 其他模型，根据任务类型动态切换
• 流式输出（Streaming）：开启 SSE 流式返回，提升长文本的交互体验
• 工具调用（Function Calling）：Gemini 支持函数调用，可对接本地文件、API
• 多模态输入：传入图片 URL 或 Base64，让 Gemini 进行图像理解