先交代背景：我日常开发用的是 OpenCode（开源 AI 编程智能体，MIT 协议），它支持接入本地知识库（RAG）。我的需求很简单——把我积累的几百份技术文档、项目规范、踩坑记录导入 OpenCode，让它在写代码时自动参考这些内部资料。
（实测）装 OpenCode 本体花了 10 分钟，配知识库花了 4 个小时。
为什么？因为中间有三道坎：向量数据库选型、嵌入模型配置、文档导入格式。每一步都能报一堆错，每一步的报错信息都像是另一个维度的语言。
这篇文章把我踩的坑全列出来，每个问题附修复方法。
在修任何报错之前，要理解数据是怎么流转的：
你的文档（MD/TXT/PDF）
↓ 切片（Chunking）
若干个小文本块（每个 500-1000 字符）
↓ 嵌入（Embedding）
每个文本块 → 一个向量（一串浮点数）
↓ 存储（Vector DB）
向量 + 原文存入向量数据库
↓ 查询（Retrieval）
用户提问 → 相似度搜索 → 返回最相关的文本块 → 喂给大模型
（来源：OpenCode 官方文档）
这四步中任何一步报错，知识库都用不了。下面按最常见的报错顺序逐个解决。
现象：
ChromaDB connection error: ConnectionRefusedError
或
Failed to connect to vector database at localhost:8000
原因：OpenCode 默认连接 localhost:8000 的 ChromaDB 服务，但你本地可能没有安装或启动 ChromaDB。
修复方法：
# pip 安装
pip install chromadb
# 验证
python3 -c "import chromadb; print(chromadb.version)"
ChromaDB 有两种运行模式：
# 模式 1：内存模式（最简单，重启后数据丢失）
python3 -c "import chromadb; chromadb.PersistentClient(path='./chroma_data')"
# 模式 2：服务端模式（推荐，数据持久化）
# 安装
pip install chromadb
# 启动服务（默认端口 8000）
chroma run --host 0.0.0.0 --port 8000 --path ./chroma_data
# 验证连接
curl http://localhost:8000/api/v1/heartbeat
# 返回 {"nanosecond heartbeat": ...} 说明 OK
（实测）90% 的"连接失败"都是因为 ChromaDB 服务没启动。OpenCode 不会自动帮你启动向量库，你得自己先跑 chroma run。
OpenCode 的向量库配置通常在 ~/.opencode/config.toml：
# 向量库配置
[rag.vector_store]
type = "chromadb"
host = "localhost"
port = 8000
# 如果 ChromaDB 和 OpenCode 不在同一台机器，改成真实 IP
# host = "192.168.1.100"
（实测）很多教程给的配置是 type = "chromadb" 但实际 ChromaDB 没装或者版本不对。装完后跑一下 chroma run 确认服务端口在 8000。
现象：
Failed to download embedding model: BAAI/bge-small-zh-v1.5
或
Model not found: text2vec-large-chinese
原因：OpenCode 默认使用 HuggingFace 的嵌入模型（如 BAAI/bge-small-zh-v1.5），但从国内下载 HuggingFace 模型经常超时。
修复方法：
# 设置 HuggingFace 国内镜像
export HF_ENDPOINT=https://hf-mirror.com
# 然后重新启动 OpenCode
opencode
# 用 huggingface-cli 从国内镜像下载
pip install huggingface-hub
huggingface-cli download BAAI/bge-small-zh-v1.5
--local-dir ./models/bge-small-zh-v1.5
--local-dir-use-symlinks=False
--endpoint https://hf-mirror.com
然后在 OpenCode 里配本地路径：
[rag.embedding]
model_path = "./models/bge-small-zh-v1.5"
# 不用在线下载
local_files_only = true
如果显存不够，用更轻量的嵌入模型：
[rag.embedding]
# 中文场景推荐
model = "shibing624/text2vec-base-chinese"
# 或英文场景
model = "sentence-transformers/all-MiniLM-L6-v2"
（实测）中文文档用 text2vec-base-chinese 效果比 bge-small 更好，而且模型只有 400MB，下载快。
现象：
Failed to parse document: unsupported file type .docx
或
No text extracted from document
原因：OpenCode 默认只支持 .txt 和 .md 文件。如果你导入了 .docx、.pdf 或其他格式，需要单独的解析工具。
修复方法：
# 把所有文档统一转换为 txt 再导入
import glob
import os
# 把 Markdown 文件内容合并到一个 txt 集合中
docs_dir = "./my_docs"
output_file = "./knowledge_base.txt"
with open(output_file, 'w', encoding='utf-8') as f:
for md in glob.glob(f"{docs_dir}/**/*.md", recursive=True):
with open(md, 'r', encoding='utf-8') as src:
content = src.read()
f.write(f"\n\n### 文档：{os.path.basename(md)}\n\n")
f.write(content)
print(f"已合并 {len(glob.glob(f'{docs_dir}/**/*.md'))} 份文档到 {output_file}")
（实测）我自己的知识库有几百份 Markdown 笔记，用这个脚本合成一个大 txt，一次性导入，比逐个导入速度快多了。但如果文件太大（>100MB），需要调整 Chunk 大小。
现象：导入成功了，但搜索时返回的内容完全不相关，或者返回空。
原因：Chunk（切片）大小和重叠量（overlap）设置不合理。
通俗讲：你把每个文档切成多大的块？如果切得太碎（比如每块 200 字），信息太分散；如果切得太粗（每块 2000 字），搜索精度差。
修复方法：
[rag.chunking]
# 中文推荐（字符数）
chunk_size = 500 # 每个块约 500 字
chunk_overlap = 50 # 相邻块重叠 50 字（避免信息被割裂）
# 如果文档是代码，改大一点
# chunk_size = 1000
# chunk_overlap = 100
（实测）给中文内容设置的黄金经验值：
chunk_size = 300chunk_size = 500（推荐）chunk_size = 800chunk_size = 1000如果你的搜索完全没结果，可能是这些值在 OpenCode 里没加。试着用 OpenCode 支持的 --chunk-size 和 --chunk-overlap 参数重新导入。
现象：
Dimension mismatch: expected 768, got 384
或
Error: vector dimensions don't match index
原因：你换了嵌入模型，但向量库里的历史数据还是旧模型生成的。不同的嵌入模型输出不同维度的向量：
| 模型 | 输出维度 | 中文支持 |
|---|---|---|
| text2vec-base-chinese | 768 | ✅ 好 |
| text2vec-large-chinese | 1024 | ✅ 好 |
| bge-small-zh-v1.5 | 512 | ✅ 一般 |
| all-MiniLM-L6-v2 | 384 | ❌ 英文为主 |
修复方法：换模型后必须重建向量库（清空旧向量数据）。
# 删除旧的向量库文件
rm -rf ./chroma_data
# 重新导入文档
opencode rag import ./my_docs --rebuild
（实测）这个报错的提示信息非常误导——它说的是"维度不匹配"，但大部分开发者看不出原因。只要你换了嵌入模型，就必须重建向量库。
把上面的踩坑经验总结成脚本：
#!/bin/bash
# OpenCode 本地知识库一键搭建
# 1. 安装 ChromaDB
echo "=== 安装 ChromaDB ==="
pip install chromadb
# 2. 启动 ChromaDB
echo "=== 启动 ChromaDB（后台） ==="
chroma run --host 0.0.0.0 --port 8000 --path ./chroma_data &
sleep 2
# 3. 验证 ChromaDB
curl -s http://localhost:8000/api/v1/heartbeat && echo "ChromaDB OK"
# 4. 设置 HuggingFace 国内镜像（加速下载）
export HF_ENDPOINT=https://hf-mirror.com
# 5. 下载嵌入模型到本地
echo "=== 下载嵌入模型 ==="
huggingface-cli download shibing624/text2vec-base-chinese
--local-dir ./models/text2vec-base-chinese --local-files-only=false
--endpoint https://hf-mirror.com
# 6. 导入知识库文档
echo "=== 导入文档 ==="
opencode rag import ./my_docs
--chunk-size 500
--chunk-overlap 50
--embedding-model ./models/text2vec-base-chinese
echo "=== 完成 ==="
把这段脚本保存成 setup_rag.sh，把 ./my_docs 改成你的文档路径，一口气搞定。
OpenCode 是一个开源工具，文档不如商业产品完善。如果上面的方法都不行，你可以：
| 工具 | 向量库方案 | 成熟度 | 推荐度 |
|---|---|---|---|
| Anything LLM | 内置 ChromaDB | ⭐⭐⭐⭐⭐ | ✅ 最省心 |
| Dify | 内置 Weaviate | ⭐⭐⭐⭐⭐ | ✅ 有 GUI |
| LangChain | 自己配 | ⭐⭐⭐ | 复杂但灵活 |
（实测）如果你只是想快速用上知识库，Anything LLM 是最省心的选择。它是专门做本地知识库的，支持 PDF/DOCX/TXT/Markdown 等格式，内置向量库，有图形界面。
from chromadb import Client
from sentence_transformers import SentenceTransformer
import glob
# 1. 嵌入模型
embedder = SentenceTransformer('shibing624/text2vec-base-chinese')
# 2. 向量库
client = Client()
collection = client.create_collection("my_knowledge_base")
# 3. 导入文档
for f in glob.glob("./my_docs/**/*.md", recursive=True):
with open(f, encoding='utf-8') as fh:
text = fh.read()
# 切片
for i in range(0, len(text), 500):
chunk = text[i:i+500]
vector = embedder.encode(chunk).tolist()
collection.add(
documents=[chunk],
embeddings=[vector],
ids=[f"{f}_{i}"]
)
# 4. 查询
query_vector = embedder.encode("用户提问的内容")
results = collection.query(query_embeddings=[query_vector.tolist()], n_results=5)
print(results['documents'])
（实测）这段 Python 脚本就是 OpenCode 知识库的"最小实现"。如果你只是想在本地验证 RAG 流程，它比 OpenCode 更直观。
观点收尾：
本地知识库的报错，80% 发生在向量数据库这一步。你花在修 ChromaDB 上的时间，可能比用它的时间还长。
五个报错的解决优先级：
chroma run 启动服务/hf-mirror.com如果修了一小时还是不行，直接用 Anything LLM 或 Dify，它们把向量库的复杂配置全封装好了。
想了解如何在本地完整搭建 AI 开发环境，看 本地部署大模型实战：Ollama + Open WebUI 完整教程。如果你对 OpenCode 本身感兴趣，我知识库里有两篇详细笔记，私我发你。
本文基于博主在本地部署 OpenCode 知识库的实测经历写成，部分 API 细节参考了 OpenCode 官方文档。