2.5 KiB
2.5 KiB
常见问题与排障
1. PowerShell 报脚本执行策略错误
看到 PSSecurityException 或 about_Execution_Policies，改用 .cmd 入口即可：
.\install.cmd
.\start_8080_toolhub_stack.cmd start
如果一定要直接调用 .ps1：
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
2. 提示 llama-server.exe 不存在
重新执行安装脚本：
.\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. 启动后模型未就绪
.\start_8080_toolhub_stack.cmd status
.\start_8080_toolhub_stack.cmd logs
首次启动需要 30–60 秒加载模型，刚启动不久的话稍等片刻。
5. 页面报内容编码错误
.\start_8080_toolhub_stack.cmd restart
如果仍然出现，清浏览器缓存后刷新。
6. 显存不足
Q4_K_M 量化下模型加上视觉投影约占 6.1 GB 显存。如果显存紧张：
缩小上下文窗口：
$env:CTX_SIZE = '8192'; .\start_8080_toolhub_stack.cmd restart
降低图像 token 上限：
$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 容器环境可用：
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，再重启容器。