103 lines
4.1 KiB
Markdown
103 lines
4.1 KiB
Markdown
# 🤖 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+ 及以下库：
|
||
```bash
|
||
pip install pyTelegramBotAPI python-dotenv duckduckgo-search beautifulsoup4 requests urllib3
|
||
```
|
||
|
||
### 2. 环境变量配置 (.env)
|
||
在项目根目录创建 `.env` 文件填入凭证：
|
||
```ini
|
||
# 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. 运行程序
|
||
```bash
|
||
cd E:\AI_Workspace
|
||
python tg_bot.py
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ 高级定制指南
|
||
|
||
### 修改 API 地址与模型
|
||
如需适配非 NVIDIA 官方接口（例如本地 Ollama 或其他云厂商）：
|
||
|
||
1. 打开 `tg_bot.py`。
|
||
2. 定位至 **核心配置区**（约第 25 行）：
|
||
```python
|
||
NVIDIA_API_URL = "https://integrate.api.nvidia.com/v1/chat/completions" # 修改此处
|
||
DEFAULT_MODEL = "openai/gpt-oss-120b" # 修改默认模型
|
||
```
|
||
3. 更新 `MODEL_MAP` 字典以匹配新提供商支持的模型 ID：
|
||
```python
|
||
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 日*
|