first

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)。