WorkBuddy部署指南：打造高效AI工作站

WorkBuddy 并非即插即用的AI工作站，而是一个高度依赖手动配置与深度调优的本地化AI工具链——从Docker网络中前后端服务名与API地址的精确匹配，到GGUF模型格式、路径及硬件适配的严苛要求，再到PDF解析时pdfminer死锁、RAG分块溢出等隐蔽陷阱，任何一处参数遗漏或权限错配都会导致加载失败、空白页面或长时间卡顿；它的“高效”并非开箱所得，而是源于你对底层模块边界条件的透彻理解与持续运维。

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 会直接拒载。

• 只认 .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 写入缓存目录。漏掉其中任意一个，它就只是个能亮屏的玩具。

今天带大家了解了的相关知识，希望对你有所帮助；关于科技周边的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~