🤖 用 Gemini + Telegram Bot 打造你的 AI 聊天助手（从零到跑通全记录）

一个下午的折腾实录 —— 70 行 Python 代码，让 Telegram 接入 Google Gemini 大模型，实现智能私聊 + 自动代回消息。

---

📖 目录

• 最终效果
• 项目简介
• 实现原理
• 环境准备
• 手把手教程
• 核心代码解析
• 踩坑记录
• 后续优化方向

---

🎉 最终效果

聊天界面

在 Telegram 里直接和 Bot 对话，Bot 背后调用 Gemini 大模型回复：

终端日志

后台可以清晰看到每条消息的收发流程、API 调用状态：

---

💡 项目简介

这是一个用 Python 写的 Telegram Bot，核心功能是：

功能	说明
🗣️ 智能对话	私聊 Bot 时，自动调用 Gemini 生成回复
🤝 自动代回	开启 Telegram Business 后，别人私聊你的个人号，Bot 会以你的名义智能回复
📝 日志监控	终端实时输出消息收发和 API 调用日志

技术栈一览：

• 语言：Python 3.10+
• Telegram SDK：python-telegram-bot v21+
• AI 模型：Google Gemini 3.8 Flash（通过 google-genai SDK 调用）
• 架构：长轮询（Long Polling）模式

---

🔧 实现原理

用户发消息 → Telegram 服务器 → Bot 轮询获取(getUpdates)
                                      ↓
                              Python 脚本接收消息
                                      ↓
                           调用 Gemini API 生成回复
                                      ↓
                         Bot 发送回复(sendMessage) → 用户看到回复

整个链路很简单，核心就是做了一个「消息中转站」：

1. Bot 通过 getUpdates 不断轮询 Telegram 服务器
2. 拿到新消息后，把文本扔给 Gemini API
3. 拿到 AI 回复后，通过 sendMessage 发回给用户

---

🛠️ 环境准备

1. 创建 Telegram Bot

1. 打开 Telegram，搜索 @BotFather
2. 发送 /newbot，按提示输入 Bot 名称和用户名
3. 拿到 Bot Token（类似 123456789:ABCdefGHIjklMNOpqrSTUvwxyz）

💡 小贴士：Bot 用户名必须以 bot 结尾，比如 larrys_gemini_bot

2. 获取 Gemini API Key

1. 访问 Google AI Studio
2. 点击 Get API Key → Create API Key
3. 复制保存好

3. 安装依赖

# 建议先创建虚拟环境
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

4. 配置环境变量

# 复制示例文件
cp .env.example .env

# 编辑 .env，填入你的密钥
TG_BOT_TOKEN=你的Telegram Bot Token
GEMINI_API_KEY=你的Gemini API Key

Windows PowerShell 临时设置：

$env:TG_BOT_TOKEN = "你的Token"
$env:GEMINI_API_KEY = "你的Key"

---

🚀 手把手教程

第一步：克隆项目

git clone https://github.com/你的用户名/telegram-gemini-bot.git
cd telegram-gemini-bot

第二步：安装 & 配置

pip install -r requirements.txt
# 设置环境变量（见上方）

第三步：运行

python telegram_bot.py

看到下面这行就说明成功了：

>>> 机器人已上线，正在监听消息...

第四步：测试

打开 Telegram，找到你的 Bot，发一条消息试试！

---

🔍 核心代码解析

整个项目只有一个 telegram_bot.py，大约 70 行代码。下面逐块拆解：

初始化 AI 客户端

from google import genai

ai_client = genai.Client(api_key=GEMINI_KEY)

用 google-genai 官方 SDK 创建客户端，一行搞定。

处理私聊消息

async def handle_direct_chat(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_text = update.message.text
    
    response = ai_client.models.generate_content(
        model='gemini-3.8-flash',    # 选用 Flash 版，响应快
        contents=user_text           # 直接把用户消息丢给模型
    )
    await update.message.reply_text(response.text)

这里选了 gemini-3.8-flash 模型，特点是响应速度快、免费额度够用，非常适合聊天场景。

处理自动代回（Business 消息）

async def handle_business(update: Update, context: ContextTypes.DEFAULT_TYPE):
    msg = update.business_message
    
    response = ai_client.models.generate_content(
        model='gemini-3.8-flash',
        contents=f"你是私人代回助手，请以本人名义礼貌自然地回复：\n{msg.text}"
    )
    await context.bot.send_message(
        chat_id=msg.chat.id,
        text=response.text,
        business_connection_id=msg.business_connection_id  # 关键！这个ID让消息以你的名义发出
    )

重点注意：business_connection_id 是 Telegram Business 功能的核心参数，有了它 Bot 才能"替你说话"。

注册消息处理器 & 启动

app = ApplicationBuilder().token(TG_BOT_TOKEN).build()

# 普通私聊用 MessageHandler
app.add_handler(MessageHandler(filters.TEXT & (~filters.COMMAND), handle_direct_chat))
# Business 消息用 TypeHandler 匹配整个 Update
app.add_handler(TypeHandler(Update, handle_business))

app.run_polling(allowed_updates=["message", "business_connection", "business_message"])

allowed_updates 参数很重要，不加 business_message 的话收不到代回消息。

---

🕳️ 踩坑记录

坑 1：第一次调用报错「模型调用出错」

现象：Bot 回复了 抱歉，模型调用出错，请检查终端日志。

原因：Gemini API Key 配置错误 / 网络问题。由于代码里有 try-except 兜底，所以不会崩溃，但会走到错误分支。

解决：

• 确认 API Key 正确
• 确认网络能访问 generativelanguage.googleapis.com
• 如果在国内，可能需要代理

坑 2：终端 Warning 刷屏

google_genai.types - WARNING - Warning: there are non-text parts in the response: 
['thought_signature'], returning concatenated text result from text parts.

原因：Gemini 3.8 Flash 有时候会在返回内容中夹带思考签名（thought_signature），SDK 会抛 Warning。

解决：这个 Warning 不影响功能，可以忽略。如果实在看着烦，可以加一行过滤日志：

logging.getLogger("google_genai.types").setLevel(logging.ERROR)

坑 3：Business 消息收不到

原因：run_polling() 默认只监听普通消息，不包含 business 类型。

解决：加上 allowed_updates 参数：

app.run_polling(allowed_updates=["message", "business_connection", "business_message"])

坑 4：Bot 回复了自己的消息导致死循环

原因：handle_business 没有过滤 Bot 自己发的消息。

解决：加一个判断：

if msg.from_user and msg.from_user.is_bot:
    return

---

🚧 后续优化方向

• 对话记忆：接入多轮对话，让 Bot 记住上下文（目前每条消息是独立的）
• System Prompt 可配置：通过命令设置 Bot 的人设和回复风格
• 群聊摘要：支持在群聊中 @Bot 让它总结聊天记录
• 图片理解：利用 Gemini 的多模态能力，支持发图片提问
• 流式回复：长回复时分段发送，体验更好
• 部署上云：用 Docker 容器化，部署到云服务器 24/7 运行

---

📁 项目结构

telegram-gemini-bot/
├── telegram_bot.py      # 主程序（全部逻辑就在这一个文件）
├── requirements.txt     # Python 依赖
├── .env.example         # 环境变量示例
├── .gitignore           # Git 忽略规则
├── LICENSE              # MIT 许可证
├── images/              # 截图
│   ├── chat_demo.jpg    # 聊天效果截图
│   └── terminal_log.png # 终端日志截图
└── README.md            # 就是这篇文章

---

⭐ 总结

一个下午的时间，70 行 Python，两个 API Key，就能让 Telegram 接入 Gemini 大模型。

核心收获：

1. Telegram Bot API 很友好 —— python-telegram-bot 库封装得很好，异步写法很优雅
2. Gemini SDK 极简 —— google-genai 一行代码就能调用，比直接 HTTP 方便太多
3. Business 消息是个宝 —— Telegram 的 Business 功能可以让 Bot 以你的名义回复别人，适合做自动客服/代回
4. 先跑通再优化 —— 别一开始就想着做完美，先让最小可用版本跑起来

如果这篇文章对你有帮助，欢迎 ⭐ Star 支持！有问题可以提 Issue 交流。

---

📜 License

MIT © Larry