168 lines
7.0 KiB
Markdown
168 lines
7.0 KiB
Markdown
|
||
# Qwen3.5-9B ToolHub 增强版 (Enhanced Edition)
|
||
> **版本标识**：原版基础功能 + 本地写作/记忆 + 混合云智能路由
|
||
> **作者**: 老王 (Lao Wang) & AI 协作伙伴
|
||
> **最后更新**: 2026-03-12
|
||
|
||
## 🚀 项目简介
|
||
本项目是基于 **Qwen3.5-9B** 多模态模型的本地一体化部署方案。它不仅具备原版的联网搜索、看图读图能力，更通过深度二次开发实现了从“只能看”到"**能写、能记、能感知**"的质变，并引入了混合云架构以应对复杂任务。
|
||
|
||
- ✅ **原生能力**：本地 GPU 推理、OpenAI 兼容 API、多模态输入。
|
||
- ⭐ **核心增强**：原子化文件写入、持久化记忆注入、实时环境感知。
|
||
- ⭐ **智能扩展**：混合云路由（本地+DeepSeek/GPT）、粘性会话切换。
|
||
|
||
---
|
||
|
||
## 🆚 版本差异对比 (原版 vs 增强版)
|
||
|
||
| 功能模块 | 原版 (Original) | 增强版 (Enhanced v2.0+) |
|
||
| :--- | :--- | :--- |
|
||
| **模型推理** | 仅本地 Qwen3.5-9B | **本地 + 云端(DeepSeek/GPT) 混合路由** |
|
||
| **文件操作** | 🔒 只读浏览 | ✏️ **原子化写入 (白名单沙盒)** |
|
||
| **记忆系统** | ❌ 无长期记忆 | 🧠 **JSON 持久化偏好库 (热加载)** |
|
||
| **网络抓取** | 普通请求 | 🛡️ **反爬优化 (User-Agent + 重试机制)** |
|
||
| **环境感知** | 静态上下文 | ⏰ **动态注入时间/日期/星期** |
|
||
| **适用场景** | 简单问答、分析 | **代码编写、长程规划、隐私数据分析** |
|
||
|
||
---
|
||
|
||
## 🛠️ 快速开始 (Quick Start)
|
||
|
||
### 1. 环境要求
|
||
- **操作系统**: Windows 10 / 11
|
||
- **硬件**: NVIDIA 显卡 (显存 ≥ 8GB, 推荐 ≥ 12GB)
|
||
- **软件**: Python 3.10+, Git, Docker (可选)
|
||
|
||
### 2. 安装与启动
|
||
#### 首次安装 (下载约 6GB 模型)
|
||
*方法 A: 标准版 (推荐)*
|
||
```bat
|
||
# 双击运行
|
||
bootstrap.bat
|
||
```
|
||
|
||
*方法 B: Q8 量化版 (显存 ≥ 12GB，占用约 10.2GB)*
|
||
```bat
|
||
# 双击运行
|
||
bootstrap_q8.bat
|
||
```
|
||
|
||
#### 启动服务
|
||
```bat
|
||
# 启动服务 (端口 8080)
|
||
.\start_8080_toolhub_stack.cmd start
|
||
|
||
# 停止服务
|
||
.\start_8080_toolhub_stack.cmd stop
|
||
```
|
||
|
||
#### 访问界面
|
||
打开浏览器访问：**http://127.0.0.1:8080**
|
||
*(注：首次启动需等待 30~60 秒加载模型)*
|
||
|
||
---
|
||
|
||
## ⚙️ 增强配置详解 (.env)
|
||
|
||
在启动前，请编辑项目根目录下的 `.env` 文件，根据需求开启增强功能。**注意路径不要带末尾斜杠**。
|
||
|
||
```ini
|
||
# ==========================================
|
||
# 🚀 核心运行模式
|
||
# ==========================================
|
||
# local = 仅使用本地 Qwen3.5-9B
|
||
# cloud = 仅使用云端模型 (需配置下方密钥)
|
||
MODEL_MODE=local
|
||
|
||
# ==========================================
|
||
# ☁️ 云端大脑配置 (DeepSeek / OpenAI 兼容)
|
||
# ==========================================
|
||
# 默认云端模型 ID (例如: deepseek-chat, gpt-4o-mini)
|
||
CLOUD_MODEL_ID=deepseek-chat
|
||
# 云端 API Base URL
|
||
CLOUD_BASE_URL=https://api.deepseek.com/v1
|
||
# 云端 API Key (请勿泄露)
|
||
CLOUD_API_KEY=sk-your-key-here
|
||
|
||
# ==========================================
|
||
# 🛠️ 文件系统增强 (写入功能)
|
||
# ==========================================
|
||
# [True/False] 是否允许 AI 物理写入本地文件
|
||
ENABLE_FILE_WRITE=True
|
||
|
||
# 📂 安全沙盒：只允许在此目录下写入 (支持多个路径用分号隔开)
|
||
# 示例: E:\AI_Workspace;D:\Projects\Temp
|
||
WRITEABLE_FS_ROOTS=E:\AI_Workspace
|
||
|
||
# ==========================================
|
||
# 🧠 持久记忆系统
|
||
# ==========================================
|
||
# 记忆文件绝对或相对路径 (必须确保目录存在)
|
||
MEMORY_FILE_PATH=./.tmp/super_agent_data/memory.json
|
||
```
|
||
|
||
---
|
||
|
||
## 🧠 核心高级功能说明
|
||
|
||
### 1. 混合云智能路由 (Hybrid Cloud Routing)
|
||
系统不再是非黑即白的单模型选择，而是基于**语义意图**和**手动指令**的智能切换：
|
||
|
||
- **自动分流**:
|
||
- **高频/隐私任务** -> 自动路由至本地 `Qwen3.5-9B` (零成本，高速度)。
|
||
- **复杂逻辑/大规模编程** -> 自动路由至云端 `DeepSeek/GPT` (强逻辑，长文本)。
|
||
- **手动干预 (粘性切换)**:
|
||
- 输入 `/cloud ...`: 强制当前及后续对话切换到云端，直到再次切换。
|
||
- 输入 `/local ...`: 强制切回本地模型。
|
||
- *特性*: 系统会记住您最近的切换指令，保持上下文一致性。
|
||
|
||
### 2. 原子化物理写入 (Atomic Write Engine)
|
||
赋予模型真正的“动手能力”，但处于严格保护中：
|
||
- **安全机制**: 只有 `WRITEABLE_FS_ROOTS` 指定的目录内的文件可被修改/创建。
|
||
- **应用场景**: 自动生成代码文件、整理日志、构建文档。
|
||
- **警告**: 严禁将 `SYSTEM` 或 `Program Files` 等系统目录加入白名单。
|
||
|
||
### 3. 持久化记忆热注入 (Persistent Memory)
|
||
- **原理**: 每次对话开始时，系统会自动读取 `memory.json` 中的内容，并将其作为 System Prompt 的一部分注入给 AI。
|
||
- **用途**: 记住您的昵称（如“老王”）、工作习惯（如“代码必须加注释”、“Markdown 格式”）、偏好设置。
|
||
- **数据格式**: 支持纯列表 `["item1"]` 或对象包装 `{"items": [...]}`，系统自动容错。
|
||
|
||
### 4. 反侦察网页抓取
|
||
针对 GitHub、Google Scholar 等高防御网站进行了优化：
|
||
- 内置主流浏览器 User-Agent 伪装。
|
||
- 集成指数退避重试策略，自动处理 HTTP 429 (Too Many Requests) 错误。
|
||
|
||
---
|
||
|
||
## 🐞 故障排查 (Troubleshooting)
|
||
|
||
| 现象 | 可能原因 | 解决方案 |
|
||
| :--- | :--- | :--- |
|
||
| **Network Error** | 网关未注册 Write 工具 | 检查 `toolhub_gateway_agent.py` 是否包含 `import agent_runtime.write_tools` |
|
||
| **AI "失忆"** | `memory.json` 格式错误 | 检查 JSON 是否有**末尾逗号**；运行诊断脚本 `python diagnose_memory.py` |
|
||
| **无法写入文件** | 路径不在白名单 | 确认写入路径是否在 `WRITEABLE_FS_ROOTS` 列表中，且目录已存在 |
|
||
| **云端切换无效** | 指令格式错误 | 确保 `/cloud` 后紧跟一个空格再写内容，如 `/cloud 帮我写个算法` |
|
||
| **HTTP 429 报错** | 频繁刷新网页 | 等待几秒重试，新版已自动处理此类重试逻辑 |
|
||
|
||
---
|
||
|
||
## 📁 常用操作指令速查
|
||
|
||
| 指令类型 | 用法示例 | 作用 |
|
||
| :--- | :--- | :--- |
|
||
| **正常对话** | `(直接输入)` | 遵循 `.env` 默认路由模式 |
|
||
| **强制云端** | `/cloud 分析一下这个复杂的架构` | 立即切换至云端大模型 |
|
||
| **强制本地** | `/local 看看我的本地日志 file.log` | 立即切换回本地小模型，节省 Token |
|
||
| **查看状态** | `(询问系统信息)` | AI 会汇报当前时间、模型负载及路由状态 |
|
||
|
||
---
|
||
|
||
## 📝 开发者笔记
|
||
- **记忆文件格式**: 建议由用户手动维护或使用官方导出工具生成，避免手滑产生非法 JSON 字符。
|
||
- **日志查看**: Windows 下直接运行批处理脚本时，命令行窗口即为实时日志终端。
|
||
- **数据安全**: 所有的模型权重、记忆文件和日志均存储在本地 (`E:\Qwen3.5...`)，不上传任何私有数据至公有云（除非明确使用 `/cloud` 处理非敏感数据）。
|
||
|
||
---
|
||
*祝你调试愉快！如有问题，请查阅 logs 文件或联系老王团队。*
|
||
|