Dify需正确配置Chroma四项参数并验证连通性：VECTOR_STORE=chroma、CHROMA_ENDPOINT=http://chroma:8000、CHROMA_COLLECTION_NAME=dify_knowledge、CHROMA_API_KEY按需设置；必须通过容器名通信、检查健康状态、确认collection存在且维度匹配，否则知识库无法生效。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在CentOS 7服务器上让Dify真正用上本地Chroma向量数据库，不能只改几个env变量就以为接通了——实际部署中，90%的“知识库不生效”“检索无结果”问题，都卡在Dify容器根本连不到Chroma服务，或连上了却因collection命名/嵌入维度/认证配置不一致导致写入静默失败。
确认Chroma服务已独立运行并可访问
进入Docker宿主机终端，执行 docker ps | grep chroma，确保看到状态为Up的chroma容器；若无输出，说明Chroma未启动或已崩溃。
运行 curl -X GET http://localhost:8000/api/v1/health，返回 {"status":"healthy"} 才代表服务监听正常；如果报错connection refused，检查docker-compose.yml中chroma服务是否暴露了8000端口且networks配置与dify同属一个自定义网络。
这一步必须在Dify启动前完成。Dify容器内部无法解析localhost，所以不要在Dify容器里curl localhost:8000——它永远失败。
配置Dify连接Chroma的四项核心参数
编辑 docker/.env 文件（不是middleware.env），添加或修改以下四行：
【VECTOR_STORE=chroma】：这是Dify向量工厂识别后端类型的开关，缺省值是weaviate，不显式设为chroma会导致整个知识库流水线跳过向量化步骤。
【CHROMA_ENDPOINT=http://chroma:8000】：注意这里必须写容器名chroma而非localhost或127.0.0.1，因为Dify容器与Chroma容器通过Docker自定义网络通信，容器名即DNS名称。
CHROMA_COLLECTION_NAME=dify_knowledge：可选，但强烈建议显式指定；若不设，Dify会按dataset_id生成随机collection名，导致同一知识库多次重载后出现多个碎片collection，检索时查不到旧数据。
CHROMA_API_KEY=your_secure_key：仅当Chroma启用了Basic Auth（推荐生产环境开启）才需配置；若Chroma未配auth，此项必须删除或留空，否则Dify会携带空header触发401拒绝。
验证向量写入是否真实发生
方法一：直接查Chroma的collection列表
在宿主机执行：curl -X GET http://localhost:8000/api/v1/collections，返回JSON中应包含你设定的dify_knowledge条目，且vector_count大于0。
方法二：触发一次文档上传并观察日志
在Dify Web界面上传一份PDF → 进入Dify容器：docker exec -it dify-api-1 bash → 实时查看日志：tail -f /app/logs/app.log；出现upserted 127 vectors into collection dify_knowledge即成功；若只有document parsed但无upsert日志，说明嵌入模型调用失败或Chroma endpoint不可达。
注意：Chroma默认不持久化数据到磁盘，容器重启后collection消失。如需保留，必须在docker-compose.yml中为chroma服务挂载volume到/chroma/chroma_db路径。
修复常见嵌入维度不匹配错误
第一步：确认你使用的嵌入模型输出维度
例如用text-embedding-ada-002是1536维，而sentence-transformers/all-MiniLM-L6-v2是384维。Dify不会自动适配，必须与Chroma collection创建时的dimension严格一致。
第二步：检查Chroma collection实际维度
执行：curl "http://localhost:8000/api/v1/collections/dify_knowledge"，查看返回中的dimension字段值。
第三步：强制重建collection（不可逆操作）
先删除旧collection：curl -X DELETE http://localhost:8000/api/v1/collections/dify_knowledge；再重启Dify服务，让它在首次向量化时按当前嵌入模型维度新建collection。
【此操作将清空该collection下所有已有向量，知识库需重新上传文档】
