WorkBuddy 部署经验分享：如何打造最高效的 AI 工作站

WorkBuddy非开箱即用，需手动配置：前端NEXT_PUBLIC_API_BASE_URL须改为http://backend:8000，后端服务名必须为backend；模型仅支持GGUF格式并正确路径配置；RAG解析PDF需禁用pdfminer防死锁；参数与权限配置任一遗漏将导致功能异常。

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

WorkBuddy 不是开箱即用的“AI工作站”，它本质是一个需要手动组装、调优和持续维护的本地化工具链——直接拉镜像跑起来，大概率卡在 model loading 或 HTTP 502，根本进不了 UI。

为什么 docker-compose up 后访问 http://localhost:3000 显示空白或连接拒绝

这不是网络问题，而是 WorkBuddy 的前端（Next.js）和后端（FastAPI）默认不共享同一 host，且前端构建时硬编码了 NEXT_PUBLIC_API_BASE_URL。Docker 网络中，前端容器无法通过 localhost 访问后端。

• 必须在 .env.local（前端目录下）里把 NEXT_PUBLIC_API_BASE_URL 改成 http://backend:8000，而非 http://localhost:8000
• 后端服务在 docker-compose.yml 中的 service name 必须叫 backend，否则前端 DNS 解析失败
• 前端镜像构建前要先运行 npm run build，否则 Dockerfile 中的 next export 会因缺少 .next 目录而静默失败

llama.cpp 模型加载失败：报错 failed to load model: unknown file format

WorkBuddy 默认期望的是 GGUF 格式模型，但很多人误用了旧版 GGML 或 PyTorch 原生权重（.bin / .safetensors），这些格式 runtime 会直接拒载。

Muse AI

下一代无广告视频托管平台

下载

• 只认 .gguf 后缀，且需确认模型量化类型匹配——比如 Q4_K_M 可以跑，但 Q2_K 在某些 CPU 上会触发 avx2 not supported
• 模型文件必须放在 models/ 目录下，并在 config.yaml 中用完整相对路径声明：model_path: "models/phi-3-mini-4k-instruct.Q4_K_M.gguf"
• 若用 Apple Silicon，记得加 LLAMA_METAL=1 环境变量，否则 fallback 到慢速 CPU 推理，首次响应常超 90 秒

上传 PDF 后 rag_pipeline 卡住，日志反复输出 chunking document...

这是 RAG 模块默认启用了 unstructured + pdfminer 双引擎解析，而 pdfminer 在处理扫描件或含复杂表格的 PDF 时会死锁，且无 timeout 控制。

• 临时解法：在 rag/config.py 中将 PDF_PARSER_ENGINE 显式设为 "unstructured"，并确保已安装 unstructured[all-docs]
• 真正稳定的做法是预处理 PDF——用 pdf2image + pytesseract 转成文本再喂给 RAG，但需额外启动 OCR 容器，WorkBuddy 官方 docker-compose 不包含此服务
• 注意 CHUNK_SIZE 和 CHUNK_OVERLAP 若设得过大（如 >1024），会导致 embedding 向量维度溢出，Silicon 芯片上尤其容易触发 bus error

WorkBuddy 的“高效”完全取决于你对它每个模块边界条件的理解程度——比如 llama.cpp 的线程数配多少、unstructured 是否启用 hi_res 模式、甚至 docker volume 的挂载权限是否允许 backend 写入缓存目录。漏掉其中任意一个，它就只是个能亮屏的玩具。