138 lines
3.2 KiB
Markdown
138 lines
3.2 KiB
Markdown
# 快速开始
|
||
|
||
从零到能用的完整说明。默认路线为 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)。
|