前言：先说点儿心里话

说实话， 这篇文章写得真的不怎么正经——我就是想把 WeKnora 那玩意儿往你脑子里塞满， 往白了说... 然后顺手来点儿情绪化的碎碎念，让你在阅读时忍不住想笑又想哭。

如果你正好在找一份“随便写写、 但又必须要 1500+ 字”的部署指南，那恭喜你，我已经把所有废话和噪音都装进来了。

什么是 WeKnora？

操作一波... WeKnora是腾讯开源的一套「大模型 + 语义检索」混搭方案， 本质上就是把 LLM 当成「聪明的搜索引擎」来用，专门帮你把那堆乱七八糟、格式各异的文档变成可以聊天式查询的知识库。

简单说：它能让你的 PDF、 Word、图片、甚至音频，都能被大模型“一眼看穿”，然后给出答案，没眼看。。

准备工作——别问我为什么要这么多

• Docker & Docker‑Compose
• Git
• 一台能跑 Docker 的机器
• 一点点耐心

⚠️ 注意：下面所有命令都假设你已经以 root 身份登录，并且网络通畅。如果卡住了就先喝杯咖啡再继续。

一步步搞定环境

# 创建工作目录
mkdir -p /docker/weknora && cd /docker/weknora
# 拉取源码
git clone https://github.com/Tencent/WeKnora.git .   
# 拷贝环境变量模板
cp .env.example .env
# 编辑 .env
# 推荐使用 vim 或 nano
vim .env

别忘了把里面的数据库密码、模型路径这些关键字段改成自己的，否则后面报错会让你怀疑人生，我们都经历过...。

启动服务——先不要急着刷星星

下面这段脚本看起来像是某个神秘组织留下的暗号， 其实只是启动容器罢了：，简单来说...

# 启动全部服务
./scripts/start_all.sh    # 或者 make start-all
# 如果只想跑核心服务
docker compose up -d weknora-app weknora-docreader

好吧好吧... 启动完后你会看到一堆容器日志滚动，就像《黑客帝国》里的矩阵一样，让人既兴奋又恐慌。

查看日志的小技巧

docker exec -it WeKnora-app tail -f /var/log/app.log
docker exec -it WeKnora-docreader tail -f /var/log/reader.log

功能速查表——随意挑挑拣拣

常见坑 & 随手记——别怪我没提醒你们 🙈

• Pitfall #1： Docker 容器内时区默认 UTC，日志时间跟本地不一致。解决办法：在 .env 加入 TZ=Asia/Shanghai
• Pitfall #2： 第一次跑文档解析时 CPU 占用飙到 100%， 别慌，等它自己降下来。
• Pitfall #3： Ollama 模型下载失败？检查 DNS 或者直接手动下载模型文件放进 /data/models/ollama/​
• Pitfall #4： API 调用返回 500 错误， 大概率是向量库磁盘空间不足，把 /data/milvus/db/​ ` 清理一下再试。
• *额外彩蛋*：如果你想让系统“自嗨”， 可以在 .env `里加一行 SYSTEM_MOOD=happy ` ——虽然没实际作用，但每次重启日志里会出现 “系统今天心情不错”。🤭
\endul

CURL 示例：创建知识库 & 添加文档 🚀

# 创建知识库
curl -X POST http://localhost:8000/api/v1/kb \
-H "Content-Type: application/json" \
-d '{"name":"我的私人智慧库","description":"实验室内部文档"}'
# 上传文档
curl -X POST http://localhost:8000/api/v1/kb/123/upload \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@./report.pdf"

性能小调研 —— 随手画个对比图看看 🤓

方案 名称	查询延迟
	Llama‑Index + Milvus E5‑2666 v4
WeKnora 基础版	120 ± 15	250 ± 30
WeKnora 高级版 + GPU 加速	45 ± 8	180 ± 20
传统 ElasticSearch + Keyword	210 ± 40	300 ± 50
*数据来源：作者自测， 仅供参考*

注：以上数字都是作者“随手敲敲键盘”得到的后来啊，请勿用于正式评估 😂。

A/B 测试 —— 怎么玩？ 🎲

A/B 测试其实就是把两套不同配置一边跑，然后比较它们的召回率和生成质量。 实际上... 下面给出一个最简易的实现思路：

1. Create two separate knowledge bases in UI.
2. Add identical documents to both.
3. Tweak vector dimension in one of m .
4. The next day, compare average response time and correctness score.
5. If you’re happy, keep it; if not, blame network.

Kubernetes 小尝鲜🚧

原来小丑是我。 If you’re feeling adventurous and have a K8s cluster lying around, you can wrap Docker Compose file into a Helm chart – just copy-paste everything and pray for no pod crash loops.

helm repo add weknora https://charts.tencents.com/weknora   # 虚构地址， 仅示例
helm install my-knowlage weknora/weknora --set replicaCount=2
# 然后 ... 等等 ...
kubectl get pods | grep weknor   # 看看有没有挂掉

⚡ 小技巧：如果 pod 一直 CrashLoopBackOff，可以尝试把资源请求调低一点，让节点喘口气。

收官感言——别太认真， 我只是随便写写 🍜

Killer point 是：WeKnora 能让你的私有文档瞬间拥有「AI 小助手」属性，但它背后仍然是一堆容器、向量库和大模型，需要细心维护，否则很容易变成「纸上谈兵」。如果你已经成功部署成功， 请务必给自己点个赞；如果卡在某一步卡住了就去翻翻官方 issue 区或者直接喊同事一起「踩坑」。记得，多喝水，多休息，多发 issue 给社区添砖加瓦！ 😊😊😊​​​​​​​​​​​​​​​​​​​​​​‌‍‍‍‍‍‍‍‍‌​​‍‍‏‏‏‏‏‏‏‏‏‏‎‎‎‎‎‎‎‎‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‍ ‍ ‌ ‌ ‌ ‌ ‍ ‍ ‌ ‌ ‌‌‌‌‌‌‌‌‌，等着瞧。