153 lines
5.1 KiB
Markdown
153 lines
5.1 KiB
Markdown
|
||
# Qwen3.5-9B ToolHub Enhanced Version
|
||
|
||
> **版本标识**：**原版基础功能 + 二开增强模块** | **Qwen3.5 多模态工具链本地一体化部署方案**
|
||
|
||
基于 Qwen3.5-9B 多模态模型 + 可调用工具的本地一体化部署方案。本项目是在原版基础上深度二次开发，实现了 AI 从"只能看"到"**能写、能记、能感知**"的质变。
|
||
|
||
---
|
||
|
||
## 📌 项目定位与声明
|
||
|
||
### 基础定位
|
||
- ✅联网搜索、看图、读文件（原版能力）
|
||
- **模型推理在本机 GPU 完成，可通过 API 接口使用**
|
||
- 需要 Windows 10/11、NVIDIA 显卡（≥8GB 显存）、Python 3.10+
|
||
|
||
### 声明
|
||
本版本由 **老王 (Lao Wang)** 及 AI 协作伙伴共同完成，旨在探索本地小规模参数模型在实际办公场景中的生产力极限。
|
||
开源致谢：[Qwen3.5](https://github.com/QwenLM/Qwen3) | [llama.cpp](https://github.com/ggml-org/llama.cpp)
|
||
|
||
---
|
||
|
||
## 🚀 核心增强功能（二开版独有）
|
||
|
||
### 1. ⚡ 原子化物理写入引擎 (Atomic Write Engine)
|
||
- **功能突破**：新增 `write_tools.py` 模块，赋予模型真正的"物理写权限"
|
||
- **静默落盘**：通过 `.env`环境变量配置 `WRITEABLE_FS_ROOTS`白名单，实现安全、极速的自动化文件保存
|
||
- **沙盒保护**：严格限制写入目录，确保系统核心文件的安全
|
||
|
||
### 2. 🧠 "睁眼即知"的持久化记忆热注入 (Persistent Memory Injection)
|
||
- **长期记忆库**：独立开发 `memory_tools.py`，支持基于 JSON 的偏好、身份和习惯存储
|
||
- **热加载技术**：重构 `toolhub_gateway_agent.py`，在每一轮对话初始化时，将 `memory.json`内容动态注入 System Prompt
|
||
- **零开销感知**：AI 无需主动翻阅本子，即可毫秒级感知用户昵称（如"老王"）、特定排版偏好（如 Markdown）等重要信息
|
||
|
||
### 3. 🛡️ 反侦察网页抓取增强 (Robust Web Fetcher)
|
||
- **HTTP 429 修复**：解决了原版抓取 GitHub 等站点时频发的 HTTP 429 错误
|
||
- **技术细节**：集成主流浏览器 User-Agent伪装，引入指数补偿重试逻辑
|
||
|
||
### 4. ⏰ 实时环境感知系统
|
||
- **时效性补全**：动态注入系统实时时间、星期及运行环境上下文，显著提升处理时间敏感型指令的准确度
|
||
|
||
---
|
||
|
||
## ✅ 完整功能清单（合并版）
|
||
|
||
| 能力类别 | 基础功能 (原版) | 增强功能 (二开) |
|
||
|---------|-----------------|---------------|
|
||
| **联网搜索** | ✅网页抓取、摘要提炼、附来源链接 | ✅反爬优化，429错误自动重试 |
|
||
| **图片处理** | ✅看图提问、局部放大、以图搜图 | - |
|
||
| **文件操作** | ✅只读浏览本机文件/日志 | ⭐原子化写入（白名单沙盒） |
|
||
| **记忆管理** | 无长期记忆 | ⭐JSON持久化偏好库 |
|
||
| **环境感知** | 基础上下文 | ⭐实时时间/星期动态注入 |
|
||
| **API接口** | ✅OpenAI兼容 API (v1) | - |
|
||
|
||
---
|
||
|
||
## 🛠️ 安装与配置（完整流程）
|
||
|
||
### 主线部署：Windows 默认方式（推荐新手）
|
||
|
||
#### 首次安装（约6GB模型）
|
||
```bash
|
||
# 方法一：标准启动脚本（双击运行）
|
||
bootstrap.bat
|
||
|
||
# 方法二：Q8量化版（显存≥12GB，占用约10.2GB）
|
||
bootstrap_q8.bat
|
||
```
|
||
|
||
#### 启动服务
|
||
```bash
|
||
.\start_8080_toolhub_stack.cmd start
|
||
# 浏览器访问 http://127.0.0.1:8080
|
||
|
||
停止：.\start_8080_toolhub_stack.cmd stop
|
||
```
|
||
|
||
> ⚠️ **每次启动需要30–60秒加载模型**
|
||
|
||
---
|
||
|
||
### 🔧 增强配置（二开版专属）
|
||
|
||
在 `.env`文件中添加以下配置以启用增强功能：
|
||
|
||
```env
|
||
# =========================================
|
||
# 【二开版】增强功能开关与路径配置
|
||
# =========================================
|
||
|
||
# ✅ 开启文件写入功能
|
||
ENABLE_FILE_WRITE=True
|
||
|
||
# 📂 写入权限白名单（沙盒保护）
|
||
WRITEABLE_FS_ROOTS=E:\AI_Workspace
|
||
|
||
# 💾 记忆文件存储路径
|
||
MEMORY_FILE_PATH=./.tmp/super_agent_data/memory.json
|
||
```
|
||
|
||
---
|
||
|
||
### 其他部署路线
|
||
|
||
- **🧊 WSL 模式** — 已有WSL环境的用户
|
||
```bash
|
||
./install.sh + ./start_8080_toolhub_stack.sh start
|
||
```
|
||
底层复用Windows主链路，适合双系统开发场景。
|
||
|
||
---
|
||
|
||
## 📖 文档导航
|
||
|
||
| 章节 | 说明 | 路径 |
|
||
|------|------|------|
|
||
| [详细介绍](docs/QUICKSTART.md) | 安装、启动、配置、服务管理 | docs/QUICKSTART.md |
|
||
| [常见问题](docs/TROUBLESHOOTING.md) | 排障指引，含HTTP 429处理 | docs/TROUBLESHOOTING.md |
|
||
| [Docker Compose](docs/DOCKER_COMPOSE.md) | 容器化部署指南 | docs/DOCKER_COMPOSE.md |
|
||
|
||
---
|
||
|
||
## 📊 系统实时状态（环境上下文）
|
||
|
||
```text
|
||
当前时间：🕒 2026-03-11 星期三 16:29:03 CST
|
||
运行模式：本地 GPU 推理 + OpenAI API兼容层
|
||
API端点：http://127.0.0.1:8080/v1
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ 启动命令速查表
|
||
|
||
| 操作 | Windows命令 |
|
||
|------|------------|
|
||
| **首次安装** | `bootstrap.bat` |
|
||
| **Q8量化版** | `bootstrap_q8.bat` (≥12GB显存) |
|
||
| **启动服务** | `.\start_8080_toolhub_stack.cmd start` |
|
||
| **停止服务** | `.\start_8080_toolhub_stack.cmd stop` |
|
||
|
||
---
|
||
|
||
## 🤝 开源致谢
|
||
|
||
- **[Qwen3.5](https://github.com/QwenLM/Qwen3)** — 通义千问多模态大模型
|
||
- **[llama.cpp](https://github.com/ggml-org/llama.cpp)** — 高性能GGUF推理引擎
|
||
|
||
---
|
||
|
||
祝你调试愉快！🚀
|
||
|