必须用docker启动chroma并配置正确网络和环境变量，再在dify中选择开源嵌入模型创建知识库，最后通过测试验证检索效果。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在Dify中快速搭建一个不依赖云服务、数据不出内网的本地知识库，必须绕过默认的远程向量数据库托管方案，直接对接本地运行的Chroma实例——这一步做错，后续所有文档切片和检索都会失败。
准备本地Chroma服务
第一步：用Docker启动Chroma，命令必须指定--host 0.0.0.0，否则Dify容器无法访问：docker run -d -p 8000:8000 --name chroma -e CHROMA_DB_IMPL=duckdb+parquet -e ALLOW_RESET=TRUE -v $(pwd)/chroma_data:/chroma_data --host 0.0.0.0:8000 chroma/chroma
第二步：验证服务是否真正就绪。直接在浏览器打开http://localhost:8000/api/v1/，看到JSON返回{"version":"0.5.3"}才算成功。如果返回连接拒绝，说明Docker网络没暴露端口或防火墙拦截了8000端口。
第三步：确认Dify所在机器能ping通Chroma服务IP。若Dify也运行在Docker中，需将Dify容器与Chroma容器置于同一自定义网络（如docker network create dify-net），并在Dify的docker-compose.yml中添加networks: [dify-net]。否则跨容器通信会失败，且错误日志里只显示“connection refused”，不提示网络隔离问题。
配置Dify连接Chroma
方法一：修改Dify环境变量（推荐用于Docker部署）
编辑.env文件，设置以下三项：
VECTOR_DATABASE=chromaCHROMA_HOST=http://host.docker.internal:8000（Mac/Windows）或CHROMA_HOST=http://172.17.0.1:8000（Linux Docker默认网关）CHROMA_SETTINGS_ANONYMOUS_TELEMETRY=false
【CHROMA_HOST必须填对，填成localhost会导致Dify容器内部解析失败】
方法二：通过Dify Web界面临时调试（仅限开发验证）
进入「Settings → Vector Database」，选择Chroma，手动输入Host地址。该方式不持久，重启后失效，仅用于快速验证连通性。
创建知识库并上传文档
第一步：登录Dify管理后台 → 点击「Knowledge Base」→ 「Create Knowledge Base」
第二步：填写名称（如“HR政策手册”），关键操作是下拉选择「Retrieval Method」为「Vector Search」，并确保右侧「Embedding Model」选的是text-embedding-ada-002以外的开源模型——本地部署必须用BGE-M3或all-MiniLM-L6-v2，否则向量维度不匹配，Chroma插入时会报dimension mismatch错误。
第三步：点击「Upload Files」，支持PDF/Word/TXT/Markdown。注意：单个文件不要超过30MB；若上传后状态卡在“Processing”，大概率是文档含复杂表格或扫描图片，需先用OCR预处理。
第四步：等待右上角出现绿色「Ready」标识，表示文档已完成切片、向量化并写入Chroma。此时可点开知识库详情页，查看「Chunks」数量是否与原文段落逻辑一致——比如一份10页PDF若只生成3个chunk，说明分块策略过于激进，需返回调整「Chunk Size」和「Overlap」参数。
测试语义检索效果
进入「Applications」→ 创建新应用 → 在「Knowledge Retrieval」模块中绑定刚建好的知识库 → 开启「Enable retrieval」→ 保存后点击「Test Chat」。
输入测试问句：“试用期可以延长吗？” → 观察右侧「Retrieved Documents」面板是否实时弹出匹配片段。若为空，先检查Chroma容器日志：docker logs chroma，常见错误是collection not found，说明Dify未成功创建collection，根源通常是CHROMA_HOST地址填错或网络不通。
若返回结果相关性低，进入知识库设置页 → 「Advanced Settings」→ 将「Top K」从默认3调至5，并勾选「Hybrid Search」启用BM25关键词回退机制。这能覆盖用户输入编号（如“制度第3.2条”）时的精确匹配需求。
