🤖 AI 代理机器人 (TG Bot)

一个基于 NVIDIA API 的多模态 Telegram 聊天机器人，具备自主搜索、深度阅读、图片识别及长期记忆管理能力。

✨ 核心特性

1. 灵活的核心架构

• API 适配层：默认对接 https://integrate.api.nvidia.com/v1/chat/completions，完全兼容所有 NVIDIA NeMo 微服务及第三方 OpenAI 协议接口。
• 动态模型切换：内置 /model 指令，实时并发检测所有注册模型的可用性（显示 ✅/❌ 状态），一键无缝切换推理引擎。
• 主脚本配置：所有核心参数（API 地址、密钥、模型列表）均在 tg_bot.py 顶部配置，无需额外配置文件即可快速迁移或私有化部署。

2. 智能 Agent 能力

• 自主决策流程：
  • 🔍 Web Search：优先使用搜索引擎获取最新信息。
  • 📄 Web Fetch：自动判断是否需要深度阅读全文（包含防 PDF 陷阱机制）。
  • 🖼️ Image Search：支持按关键词实时检索图片并返回 Markdown 格式展示。
  • 🧠 Memory Mgmt：内置单用户级长期记忆存储 (user_memory.json)，支持添加、查询、删除关键个人偏好。
• 上下文优化：
  • 自动压缩长对话历史，保留 System Prompt 和最近 20 轮有效信息。
  • 防止重复抓取同一 URL，节省 Token 消耗。

3. 输出优化

• 移动端友好：强制禁用 Markdown 表格，转换为清晰的无序列表格式，完美适配 Telegram 客户端渲染。
• 流式状态反馈：发送消息后立即编辑占位符文字（如“正在搜索..."、“正在深度阅读...”），提升交互体验。

---

🚀 快速开始

1. 环境依赖

确保已安装 Python 3.8+ 及以下库：

pip install pyTelegramBotAPI python-dotenv duckduckgo-search beautifulsoup4 requests urllib3

2. 环境变量配置 (.env)

在项目根目录创建 .env 文件填入凭证：

# Telegram Bot Token
TELEGRAM_BOT_TOKEN=your_telegram_token_here

# NVIDIA API Key (或其他兼容接口的 Key)
NVIDIA_API_KEY=nvapi-your-key-here

# 允许使用的用户 ID (逗号分隔，为空则不限)
ALLOWED_USERS=123456789,987654321

3. 运行程序

cd E:\AI_Workspace
python tg_bot.py

---

⚙️ 高级定制指南

修改 API 地址与模型

如需适配非 NVIDIA 官方接口（例如本地 Ollama 或其他云厂商）：

1. 打开 tg_bot.py。
2. 定位至 核心配置区（约第 25 行）：

   NVIDIA_API_URL = "https://integrate.api.nvidia.com/v1/chat/completions" # 修改此处
   DEFAULT_MODEL = "openai/gpt-oss-120b"                                  # 修改默认模型
   

3. 更新 MODEL_MAP 字典以匹配新提供商支持的模型 ID：

   MODEL_MAP = {
       "my-custom-model": "namespace/model-id", # 格式：display_name: api_model_id
       ...
   }
   

扩展自定义工具

在 TOOLS 列表中定义新的 Function Schema，并在 execute_* 系列函数中实现具体逻辑。

---

📂 项目结构

文件名	说明
tg_bot.py	主程序。包含核心逻辑、Tool 定义、API 调用及 Telegram 事件处理。
.env	敏感配置。Token 与 API Key 存放处，严禁提交到公共仓库。
user_memory.json	运行时自动生成。存储每个 ChatID 对应的长期记忆数据。
README.md	本项目文档。

---

💡 常见问题 (FAQ)

• Q: 为什么某些模型显示 ❌？ A: 可能是网络超时或 API Key 权限不足。检查 .env 中的 Key 是否正确，并确保网络能访问目标端点。
• Q: 内存占用过高怎么办？ A: 每次重启程序会重置 chat_memory 缓存（但保留 user_memory.json 中的持久记忆）。长时间运行建议定期 /reset 清理过长的上下文窗口。
• Q: 图片如何处理？ A: 上传的图片会被编码为 Base64 并通过 image_url 字段发送给支持视觉的模型；若需搜图，请使用自然语言描述意图（如“帮我找一张...的照片”），触发 image_search 工具。

---

最后更新时间：2026 年 03 月 14 日