WeKnora 上传文档无法正常解析怎么办检查 Embedding 与对话模型配置【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnoraWeKnora 部署起来后最典型的一类故障是服务能正常启动但上传文档时失败或文档一直处理不下去。官方常见问题docs/QA.md 第 3 条给出的结论是这类问题通常是Embedding 模型和对话模型没有正确被设置导致。本文按「查配置 → 测连通性 → 核对维度 → 看日志」的顺序把这条排查路径整理成可执行的步骤让你能定位到具体是哪个模型配置出了问题并验证修复是否生效。现象确认先判断故障卡在哪个环节排查前先确认现象属于哪一种两条线索都来自官方文档上传直接失败对应 docs/QA.md 第 3 条描述的现象文档指出的首要原因是 Embedding 模型和对话模型未正确设置。文档长时间停在「处理中」0.6.1 起每个文档解析都会记录一棵 Span 树可以在知识库卡片菜单或卡片上的「Trace」入口打开侧边时间线逐阶段看进度卡在哪个阶段解析 / 切分 / 向量化 / 后处理。如果卡在向量化阶段基本就指向 Embedding 模型问题确认某次解析挂死时也可以在时间线面板点击「中止解析」让文档结束流程详见 docs/QA.md 第 14 条。检查.env中的模型变量打开部署目录下的.env文件核对模型相关变量是否完整。按 docs/QA.md 的说明必须配置的是# LLM Model INIT_LLM_MODEL_NAMEyour_llm_model # Embedding Model INIT_EMBEDDING_MODEL_NAMEyour_embedding_model # Embedding模型向量维度 INIT_EMBEDDING_MODEL_DIMENSIONyour_embedding_model_dimension # Embedding模型的ID通常是一个字符串 INIT_EMBEDDING_MODEL_IDyour_embedding_model_id上面的值需要替换为你实际部署使用的模型名和维度。在此基础上按部署方式补两项检查使用 Ollama 本地模型需要确保本地 Ollama 服务正常运行.env中的OLLAMA_BASE_URL指向可达的地址模板中默认为http://host.docker.internal:11434参见 .env.example。通过 remote API 访问模型还需要为两类模型分别提供BASE_URL和API_KEY# LLM模型的访问地址 INIT_LLM_MODEL_BASE_URLyour_llm_model_base_url # LLM模型的API密钥如果需要身份验证可以设置 INIT_LLM_MODEL_API_KEYyour_llm_model_api_key # Embedding模型的访问地址 INIT_EMBEDDING_MODEL_BASE_URLyour_embedding_model_base_url # Embedding模型的API密钥如果需要身份验证可以设置 INIT_EMBEDDING_MODEL_API_KEYyour_embedding_model_api_key启用了重排序功能还需额外配置 Rerank 模型的INIT_RERANK_MODEL_NAME、INIT_RERANK_MODEL_BASE_URL、INIT_RERANK_MODEL_API_KEY。未启用重排序则跳过。另外注意变量命名的一个版本差异docs/QA.md 使用的是INIT_*前缀而当前 .env.example 中面向 config/builtin_models.yaml 声明式内置模型config/builtin_models.yaml中${NAME}占位符的参考命名是LLM_MODEL_NAME、EMBEDDING_MODEL_NAME、RERANK_MODEL_NAME等。两套写法分别对应不同配置通道排查时以你自己部署实际使用的那一份为准不要混填。在「设置 → 模型」页测试连通性配置修好后不一定非要重启验证。WeKnora 的模型管理见 website-docs/03-features/06-models.md提供了两层验证手段测试连接在「设置 → 模型」中添加或编辑模型时填写模型名称、服务地址与凭据后先点「Test connection」再保存。文档明确要求「保存前测试连接」确认服务地址、凭据和模型名称可用后再将模型用于知识库或智能体。各模型类型有对应的服务端检查接口如 Embedding 的POST /initialization/embedding/test、对话模型的POST /initialization/remote/check请求可携带modelId复用已存储的凭据前端拿不到明文密钥。模型调试器对已保存的模型发起真实调用。Embedding 类型会返回向量与维度可以直接用它核对向量维度是否符合预期Rerank 返回打分结果Chat 走流式并聚合观测项。调试接口为POST /models/:id/debug响应含elapsed_ms和脱敏后的请求预览。如果用的是 Agent 场景0.6.3 起还有第三道校验Agent 选择器会做模型就绪校验绑定的 LLM / Embedding / Rerank / VLM 缺失或配置无效时会直接阻断对话并给出修复指引可以在模型卡片打开调试抽屉先测连通性docs/QA.md 第 27 条。核对向量维度与索引的一致性Embedding 相关的两个约束容易踩坑都在模型管理文档和 FAQ 中写明维度必须与向量库索引匹配。FAQ 第 26 条若向量库索引维度与模型不一致检索可能异常请保持知识库绑定的向量库与模型维度一致。编辑 Embedding 模型时可在「设置 → 模型」填写dimensions覆盖值如 1024、1536。更换向量模型需要重建索引。模型决定向量的语义空间与维度新旧向量不能直接混用所以换 Embedding 模型后要对知识库重建索引而不是只改配置。查看服务日志确认错误完成配置修改并重启服务后用官方 FAQ 给出的日志命令确认是否还有报错docker compose logs -f app docreader postgres文档的判定标准是检查主服务日志中是否还有ERROR日志输出。模型配置类问题通常会在主服务app日志中暴露例如模型调用失败、连接失败等错误行。验证修复与后续处理修复完成的确认方式是回到最初的现象再操作一次重新上传一份文档观察解析时间线能推进过向量化阶段、文档状态不再失败或挂死。若时间线显示进度正常走完说明模型链路已通。几个边界情况文档有明确说法升级后解析时间线没有数据确认数据库迁移000055_knowledge_processing_spans、000056_knowledge_pending_subtasks已执行服务启动会自动迁移。后台解析任务积压或失败0.7.0 起系统管理员可在「系统设置 → 运行时队列」查看队列深度、按模型并发统计和失败任务详情并可手动重试docs/QA.md 第 30 条。如果按以上步骤仍未解决官方 FAQ 的收尾建议是在 issue 中描述问题并提供必要的日志信息辅助排查docker compose logs -f app docreader postgres的输出即可作为主要材料。【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考