first

2026-03-11 16:49:00 +08:00
commit 52d7d14795
53 changed files with 4991 additions and 0 deletions
--- a/docs/DOCKER_COMPOSE.md
+++ b/docs/DOCKER_COMPOSE.md
@@ -0,0 +1,84 @@
+# Docker Compose
+
+ToolHub 提供 Docker Compose 入口，适合 Linux 主机部署，或不想在 Windows 宿主机安装 Python 的用户。这是一条可选路线，不替代 Windows 原生脚本主线。
+
+---
+
+## 前提条件
+
+- Docker 和 Docker Compose 已安装
+- NVIDIA GPU 驱动已安装，且 NVIDIA Container Toolkit 可用
+
+验证 GPU 容器环境：
+
+```bash
+docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi
+```
+
+---
+
+## 启动与停止
+
+```bash
+docker compose up --build         # 前台启动
+docker compose up --build -d      # 后台启动
+docker compose down               # 停止
+```
+
+首次启动时后端容器会自动下载模型文件，之后缓存在 Docker 命名卷 `toolhub-models` 中。
+
+启动后浏览器访问 [http://127.0.0.1:8080](http://127.0.0.1:8080)。
+
+如果后端还在下载模型或加载模型到 GPU，浏览器会先显示准备中页面。此时直接查看：
+
+```bash
+docker compose logs -f backend
+```
+
+确认下载和加载进度即可。
+
+---
+
+## 容器结构
+
+Compose 启动两个服务：
+
+| 服务 | 镜像基础 | 职责 |
+| --- | --- | --- |
+| `gateway` | `python:3.11-slim` | 网关层，提供网页入口和 OpenAI 兼容 API（端口 8080） |
+| `backend` | `ghcr.io/ggml-org/llama.cpp:server-cuda` | 模型后端，GPU 推理（端口 8081） |
+
+架构与 Windows 原生路线一致：浏览器访问网关，网关将推理请求转发给后端。网关容器通过只读方式挂载项目目录（`/workspace`），文件系统访问行为与 Windows 路线保持一致。
+
+---
+
+## 模型管理
+
+模型不会打进镜像，由后端容器首次启动时从 Hugging Face 下载，缓存在命名卷 `toolhub-models` 中。默认下载 Q4_K_M 量化。
+
+如需切换到 Q8，在 `.env` 中将 `MODEL_GGUF_URL` 改为 Q8 下载地址，也可以先在宿主机执行 `.\install_q8.cmd` 让它自动修改，然后重启容器：
+
+```bash
+docker compose down
+docker compose up --build -d
+```
+
+> 容器内模型缓存（命名卷）和 Windows 路线的本地缓存（`.tmp/models/`）是两套独立缓存，互不影响。
+
+---
+
+## 配置
+
+Compose 通过 `.env` 文件读取配置。以下变量会影响容器行为：
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `GATEWAY_PORT` | `8080` | 网关对外端口 |
+| `BACKEND_PORT` | `8081` | 后端对外端口 |
+| `THINK_MODE` | `think-on` | 思考模式 |
+| `CTX_SIZE` | `16384` | 上下文窗口大小 |
+| `IMAGE_MIN_TOKENS` | `256` | 图像最小 token 数 |
+| `IMAGE_MAX_TOKENS` | `1024` | 图像最大 token 数 |
+| `MMPROJ_OFFLOAD` | `off` | 视觉投影卸载开关 |
+
+修改 `.env` 后重启容器生效。
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -0,0 +1,137 @@
+# 快速开始
+
+从零到能用的完整说明。默认路线为 Windows 原生，WSL 和 Docker Compose 见末尾。
+
+---
+
+## 系统要求
+
+| 项目 | 要求 |
+| --- | --- |
+| 操作系统 | Windows 10 / 11 |
+| GPU | NVIDIA，驱动 ≥ 525，建议 ≥ 8 GB 显存 |
+| Python | 3.10+，已加入 PATH |
+| 磁盘 | ≥ 20 GB 可用空间 |
+
+> Q4_K_M 量化下模型加上视觉投影约占 6.1 GB 显存。8 GB 显存可正常运行。
+
+Docker Compose 路线不需要在宿主机安装 Python，系统要求见 [Docker Compose 文档](DOCKER_COMPOSE.md)。
+
+---
+
+## 1. 安装
+
+双击 `bootstrap.bat`，或在命令行执行：
+
+```powershell
+.\install.cmd
+```
+
+安装脚本会自动完成：
+
+- 创建 Python 虚拟环境并安装依赖
+- 下载 llama.cpp CUDA 运行时
+- 下载 Qwen3.5-9B Q4_K_M 主模型与 mmproj 视觉投影模型
+
+首次安装需要下载约 6 GB 模型文件，请确保网络通畅。
+
+---
+
+## 2. 启动
+
+```powershell
+.\start_8080_toolhub_stack.cmd start
+```
+
+首次启动需要 30–60 秒加载模型到 GPU。看到"栈已启动"即表示就绪。
+
+---
+
+## 3. 打开网页
+
+浏览器访问 [http://127.0.0.1:8080](http://127.0.0.1:8080)。
+
+---
+
+## 4. 服务管理
+
+```powershell
+.\start_8080_toolhub_stack.cmd start     # 启动
+.\start_8080_toolhub_stack.cmd stop      # 停止
+.\start_8080_toolhub_stack.cmd restart   # 重启
+.\start_8080_toolhub_stack.cmd status    # 查看状态
+.\start_8080_toolhub_stack.cmd logs      # 查看日志
+```
+
+---
+
+## 5. 可选：升级到 Q8 量化
+
+显存 ≥ 12 GB 时，可以切换到 Q8 获得更高推理精度。
+
+双击 `bootstrap_q8.bat`，或执行 `.\install_q8.cmd`。脚本会自动修改 `.env` 中的模型路径和下载地址，然后开始下载。视觉模型 mmproj 不需要更换。
+
+下载完成后执行 `.\start_8080_toolhub_stack.cmd restart` 切换。
+
+---
+
+## 6. 配置
+
+复制 `.env.example` 为 `.env`，按需修改，启动脚本会自动加载。
+
+常见调整：
+
+**切换思考模式：**
+
+```powershell
+$env:THINK_MODE = 'think-off'; .\start_8080_toolhub_stack.cmd restart
+```
+
+**缩小上下文以节省显存：**
+
+```powershell
+$env:CTX_SIZE = '8192'; .\start_8080_toolhub_stack.cmd restart
+```
+
+**扩大文件系统可读范围：** 修改 `.env` 中的 `READONLY_FS_ROOTS`，多个目录用分号分隔。留空时默认只读项目目录。
+
+修改后执行 `.\start_8080_toolhub_stack.cmd restart` 生效。
+
+---
+
+## 7. API 调用
+
+网关兼容 OpenAI API 格式：
+
+```bash
+curl http://127.0.0.1:8080/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "Qwen3.5-9B-Q4_K_M",
+    "stream": true,
+    "messages": [
+      {"role": "user", "content": "今天有什么科技新闻？"}
+    ]
+  }'
+```
+
+支持 OpenAI API 的客户端可将 Base URL 设为 `http://127.0.0.1:8080/v1`。
+
+---
+
+## 其他入口
+
+### WSL
+
+WSL 入口复用 Windows 主链路，不会创建独立的 Linux 虚拟环境。
+
+```bash
+./install.sh                             # 安装
+./start_8080_toolhub_stack.sh start      # 启动
+```
+
+服务管理命令与 Windows 一致，把 `.cmd` 换成 `.sh` 即可。
+
+### Docker Compose
+
+不需要在宿主机安装 Python 或手动下载模型。详见 [Docker Compose 文档](DOCKER_COMPOSE.md)。
--- a/docs/RELEASE_NOTES.md
+++ b/docs/RELEASE_NOTES.md
@@ -0,0 +1,21 @@
+# RELEASE NOTES
+
+## v1.0.0
+
+发布日期：2026-03-04
+
+主要内容：
+
+- 交付范围固定为 Qwen3.5-9B
+- 入口固定为 8080 网页
+- 工具能力集成到 8080 网关
+- 支持流式输出与思维链输出
+- 回答下方显示性能统计
+- 思维链 token 计入统计
+- 输入栏上方实时统计隐藏
+- 提供安装脚本、启动脚本和文档
+
+限制：
+
+- 仅支持 9B 模型
+- 仅支持本机部署
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -0,0 +1,116 @@
+# 常见问题与排障
+
+---
+
+## 1. PowerShell 报脚本执行策略错误
+
+看到 `PSSecurityException` 或 `about_Execution_Policies`，改用 `.cmd` 入口即可：
+
+```powershell
+.\install.cmd
+.\start_8080_toolhub_stack.cmd start
+```
+
+如果一定要直接调用 `.ps1`：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
+```
+
+---
+
+## 2. 提示 llama-server.exe 不存在
+
+重新执行安装脚本：
+
+```powershell
+.\install.cmd
+```
+
+完成后确认文件存在：`.tmp\llama_win_cuda\llama-server.exe`。
+
+---
+
+## 3. 提示模型文件不完整
+
+检查以下两个文件是否存在且大小正常：
+
+- `.env` 里 `MODEL_PATH` 指向的主模型文件，默认为 `Qwen3.5-9B-Q4_K_M.gguf`，执行过 Q8 安装则为 `Qwen3.5-9B-Q8_0.gguf`
+- `.tmp\models\crossrepo\lmstudio-community__Qwen3.5-9B-GGUF\mmproj-Qwen3.5-9B-BF16.gguf`
+
+文件残缺或为 0 字节时，删除后重新执行 `.\install.cmd`。
+
+---
+
+## 4. 启动后模型未就绪
+
+```powershell
+.\start_8080_toolhub_stack.cmd status
+.\start_8080_toolhub_stack.cmd logs
+```
+
+首次启动需要 30–60 秒加载模型，刚启动不久的话稍等片刻。
+
+---
+
+## 5. 页面报内容编码错误
+
+```powershell
+.\start_8080_toolhub_stack.cmd restart
+```
+
+如果仍然出现，清浏览器缓存后刷新。
+
+---
+
+## 6. 显存不足
+
+Q4_K_M 量化下模型加上视觉投影约占 6.1 GB 显存。如果显存紧张：
+
+**缩小上下文窗口：**
+
+```powershell
+$env:CTX_SIZE = '8192'; .\start_8080_toolhub_stack.cmd restart
+```
+
+**降低图像 token 上限：**
+
+```powershell
+$env:IMAGE_MAX_TOKENS = '512'; .\start_8080_toolhub_stack.cmd restart
+```
+
+也可以直接修改 `.env` 里对应的值，然后重启。
+
+---
+
+## 7. 看不到回答下方的性能统计
+
+重启服务后发一条新消息即可看到。旧消息不会回填统计数据。
+
+---
+
+## 8. WSL 相关
+
+WSL 入口复用 Windows 主链路。如果 WSL 中找不到 `powershell.exe`，检查 WSL 配置中 `interop` 是否被禁用。
+
+---
+
+## 9. Docker Compose 相关
+
+### 容器启动失败
+
+确认 GPU 容器环境可用：
+
+```bash
+docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi
+```
+
+如果无法正常输出显卡信息，先解决 GPU 容器环境问题。
+
+### 模型下载失败
+
+容器首次启动时自动下载模型。下载失败时可通过 `.env` 覆盖 `MODEL_GGUF_URL` 和 `MODEL_MMPROJ_URL` 指向更快的源，再执行 `docker compose up --build`。
+
+### 端口冲突
+
+修改 `.env` 中的 `GATEWAY_PORT` 和 `BACKEND_PORT`，再重启容器。