拓冰网站定制 
llm-wiki-compiler 常见问题与故障排查指南过期页面修复、状态恢复、Embedding 失败与性能调优完整清单【免费下载链接】llm-wiki-compilerThe knowledge compiler. Raw sources in, interlinked wiki out. Inspired by Karpathys LLM Wiki pattern.项目地址: https://gitcode.com/gh_mirrors/ll/llm-wiki-compilerllm-wiki-compilerllmwiki是一个「知识编译器」输入原始资料URL、文档、笔记、PDF输出可交叉引用、可语义检索的 Markdown Wiki。本文面向新手汇总了一份llm-wiki-compiler 常见问题与故障排查清单覆盖四大高频场景过期页面Stale Pages的检测与修复、state.json状态损坏或版本过新的恢复、Embedding 嵌入失败的排查与恢复以及编译慢、检索退化时的性能调优参数。照着清单自查基本能解决 90% 的日常故障 一、排障第一步用 status 与 lint 摸清项目状态遇到任何异常先别急着重新编译。llmwiki 提供了三个只读的诊断入口它们不调用 LLM、不需要 API Key全部基于磁盘状态实时计算命令作用关注什么llmwiki status项目健康快照stateStatus是否为okstale / orphaned 页面数量待编译、待审查的积压llmwiki lint质量检查stale-page、orphaned-page规则命中的具体页面与责任源文件llmwiki next下一步建议当存在过期页面时它会自动推荐refresh --stale一个健康项目的status输出形如llmwiki status # ✓ Fresh: no stale or orphaned pages # ✓ State: ok若出现State: missing — run llmwiki compile或State: corrupt说明状态文件有问题直接跳到第三节处理。更多细节见 docs/cli/status.mdx 与 docs/troubleshooting/faq.mdx。二、过期页面Stale Pages与孤儿页面检测与一键修复核心机制每个 wiki 页面在编译时都会记录「由哪些源文件生成 内容哈希」。之后每次执行命令llmwiki 都会把记录的哈希与sources/磁盘现状对比——这就是源新鲜度追踪。两种新鲜度状态怎么区分Stale过期源文件还在但内容改了或多源页面中部分源被删除。页面还能读但可能已不代表最新资料。Orphaned孤儿生成该页面的所有源文件都被删除了页面已无法再生是清理候选。⚠️ 注意llmwiki query --save保存的问答页是生成答案永远不会被标记为过期。三步修复流程推荐顺序第 1 步查看哪些页面过期llmwiki lint # 关注规则名 stale-page 与 orphaned-page 的结果第 2 步预览修复计划零成本llmwiki refresh --stale --dry-run--dry-run只打印计划——哪些源会重编译、哪些孤儿页会被删除——不发生任何 LLM 调用不写盘。第 3 步执行修复llmwiki refresh --stale它只做三件事重编译「变更且拥有过期页」的源、清理孤儿页面纯文件操作、免 API Key、不碰无关页面。若所有过期页都是孤儿只是删源文件整个修复甚至不需要配置任何凭证。防止问题积累编辑期间保持llmwiki watch运行文件一保存就自动增量重编译过期页几乎不会堆积。完整的生命周期说明见 docs/troubleshooting/stale-pages.mdx。 小提示llmwiki view打开的 Viewer 会在页面元数据栏显示STALE / ORPHANED徽标顶部横幅显示整库新鲜度判定——不敲命令也能肉眼发现过期页。三、state.json 损坏或被新版本写入两种恢复路径.llmwiki/state.json是增量编译的账本带有 schemaversion字段。当它由更新版本的 llmwiki 写入比如同事用了新版本编译过当前构建会故意失败关闭并报错.llmwiki/state.json (version 3) was written by a newer llmwiki version (this build understands up to version 2). Upgrade llmwiki to read this project.这是设计好的安全行为宁可不读也不冒险误读或覆盖。你有两条路可走路线 A升级 llmwiki推荐npm install -g llm-wiki-compilerlatest升级后直接读取现有状态增量编译记录完整保留。路线 B重置状态文件保留备份llmwiki state reset # 先预览不做任何修改 llmwiki state reset --yes # 确认执行备份为 state.json.bak 后移除原文件 llmwiki compile # 从当前 sources/ 重建状态state reset --yes直接操作原始字节、从不解析状态文件因此即使文件「太新或损坏」也能可靠执行。原内容原子备份在.llmwiki/state.json.bak以后升级了版本还可以改回去。状态缺失或 JSON 损坏时lint和status会报告stateStatus: missing / corrupt并把所有页面标为unverifiedViewer 顶部出现损坏横幅。恢复方法统一是重新完整编译llmwiki compile官方恢复手册见 docs/troubleshooting/state-recovery.mdx新鲜度判定算法的源码位于 src/freshness/。四、Embedding 失败从报错到恢复的完整排查4.1 最常见ProviderUnavailableError跑compile时若报ProviderUnavailableError含义是找不到有效的 LLM 凭证——此时没有任何 LLM 调用发生、没有写入任何内容可安全重试。排查顺序默认 Anthropic 供应商确认ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN已设置二选一即可。若已配置本地 Claude Code~/.claude/settings.json的env块裸跑llmwiki compile应自动兜底读取。不想用 API Key可切换到免 Key 方案LLMWIKI_PROVIDERclaude-agent用本地 Claude Code 登录、ollama本地模型或copilot。4.2 query 检索不到相关内容llmwiki query的语义检索依赖嵌入索引.llmwiki/embeddings.bin或embeddings.json。索引缺失时会自动降级为纯词法BM25检索——能用但排序质量下降。常见原因当前供应商不支持嵌入copilot与claude-agent不暴露嵌入端点。claude-agent可设VOYAGE_API_KEY开启或显式指定LLMWIKI_EMBEDDING_PROVIDER如ollama免 Key。全新项目先跑一次llmwiki compile页面与嵌入会一起构建。⚠️ 若报embedding-store-unavailable说明索引文件存在但无法加载损坏。不要删除二进制索引去回退旧 JSON 快照——正确做法是执行llmwiki compile它会自动发现缺失向量并重建注意重建会消耗嵌入 API 额度隔离页除外。4.3 嵌入重试与隔离Quarantine机制嵌入生成失败时llmwiki 在.llmwiki/pending-embeddings.json中记录持久化重试预算同内容连续 5 次失败后页面被移入.llmwiki/quarantined-embeddings.json后续刷新跳过它让其他页面正常嵌入。内容一旦变化会以全新预算自动重试。排查信号看status输出的告警码embeddings-refresh-pending等待再次嵌入的页面embeddings-refresh-quarantined已耗尽重试、被隔离的页面修复供应商后的正确重置姿势① 确认没有 compile/refresh 在运行② 从两个标记文件中移除该页面条目重置全部则删除两个文件③ 重新llmwiki compile。注意只改嵌入配置不会清除隔离状态。4.4 切换嵌入后端会重建整个索引索引会记录生产它的供应商、模型与端点。修改LLMWIKI_EMBEDDING_PROVIDER/LLMWIKI_EMBEDDING_MODEL/ 端点后即使没有任何源变更下次 compile 也会重新嵌入全部合格页面有 API 成本。不同后端产出的向量不可比较重建前 query 会报告索引过时并退回词法排序。例外anthropic与claude-agent之间切换不重建二者走同一 Voyage 模型。五、性能调优清单让 compile 更快、检索更稳✅ 首次编译慢是正常现象所有源要走「概念提取 → 页面生成」两阶段流水线之后的编译是增量的未变更语料通常几秒完成。想进一步优化按此清单逐项检查环境变量默认值调优场景LLMWIKI_COMPILE_CONCURRENCY5冷启动/大批量刷新慢 → 调高上限 50可用--concurrency单次覆盖被供应商限流 → 调低LLMWIKI_PROMPT_BUDGET_CHARS200000stderr 频繁出现截断警告热门概念共享源过多→ 为大上下文模型调高如400000LLMWIKI_EMBED_BATCH_SIZE按供应商 64~256减少请求往返次数触到供应商上限则调低超上限会被钳制并告警LLMWIKI_EMBED_STRICT未设置CI 中设为1嵌入失败直接非零退出而非警告继续LLMWIKI_REQUEST_TIMEOUT_MS供应商内置openai 10 分钟 / ollama 30 分钟慢网关或本地模型超时 → 调大毫秒数LLMWIKI_STAGE_TIMING_FILE关闭设为绝对路径后compile/query 逐阶段追加 JSON 计时detect-changes、extraction、page-generation、embeddings 等精确定位慢在哪一步LLMWIKI_VERBOSE未设置任意非空值等价于--verbose查看分步进度与总耗时四条实用策略小步快跑大语料先用llmwiki quickstart 单个源跑通再增量加入其余源。换更快的模型设LLMWIKI_MODEL为供应商的轻量模型变体。大索引自动走二进制存储超过 64 MiB 的 JSON 上限后自动切换embeddings.bin无需手动干预上限512 MiB 文件 / 10 万条记录。编辑期开 watchllmwiki watch实时增量重编译避免积压。完整变量参考含调试开关LLMWIKI_DEBUG见 docs/configuration/environment-variables.mdx。六、症状速查表症状最可能原因快速修复ProviderUnavailableErrorAPI Key 未设置配置ANTHROPIC_API_KEY或切换免 Key 供应商lint报stale-page源文件内容已变更llmwiki refresh --stale先--dry-runstatus报State: corruptstate.json 不可读llmwiki compile重建报错「written by a newer llmwiki version」新版本写过状态升级 llmwiki或llmwiki state reset --yesquery 结果相关性差嵌入索引缺失配置LLMWIKI_EMBEDDING_PROVIDER后 compileembedding-store-unavailable索引损坏llmwiki compile自动重建索引compile 首次极慢全量两阶段编译属正常后续用LLMWIKI_COMPILE_CONCURRENCY提速CI 中嵌入静默失败非严格模式只告警设LLMWIKI_EMBED_STRICT1七、相关文档与源码路径故障排查 FAQdocs/troubleshooting/faq.mdx过期页面检测与修复docs/troubleshooting/stale-pages.mdx状态版本恢复手册docs/troubleshooting/state-recovery.mdx环境变量全参考嵌入重试与隔离、存储上限docs/configuration/environment-variables.mdxstatus 命令输出字段docs/cli/status.mdx新鲜度追踪实现src/freshness/lint 规则实现src/linter/ 记住排障口诀先看status定方向再用lint定页面dry-run预览后才动手compile兜底一切状态问题。【免费下载链接】llm-wiki-compilerThe knowledge compiler. Raw sources in, interlinked wiki out. Inspired by Karpathys LLM Wiki pattern.项目地址: https://gitcode.com/gh_mirrors/ll/llm-wiki-compiler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 llm-wiki-compiler 常见问题与故障排查指南：过期页面修复、状态恢复、Embedding 失败与性能调优完整清单
llm-wiki-compiler 常见问题与故障排查指南过期页面修复、状态恢复、Embedding 失败与性能调优完整清单【免费下载链接】llm-wiki-compilerThe knowledge compiler. Raw sources in, interlinked wiki out. Inspired by Karpathys LLM Wiki pattern.项目地址: https://gitcode.com/gh_mirrors/ll/llm-wiki-compilerllm-wiki-compilerllmwiki是一个「知识编译器」输入原始资料URL、文档、笔记、PDF输出可交叉引用、可语义检索的 Markdown Wiki。本文面向新手汇总了一份llm-wiki-compiler 常见问题与故障排查清单覆盖四大高频场景过期页面Stale Pages的检测与修复、state.json状态损坏或版本过新的恢复、Embedding 嵌入失败的排查与恢复以及编译慢、检索退化时的性能调优参数。照着清单自查基本能解决 90% 的日常故障 一、排障第一步用 status 与 lint 摸清项目状态遇到任何异常先别急着重新编译。llmwiki 提供了三个只读的诊断入口它们不调用 LLM、不需要 API Key全部基于磁盘状态实时计算命令作用关注什么llmwiki status项目健康快照stateStatus是否为okstale / orphaned 页面数量待编译、待审查的积压llmwiki lint质量检查stale-page、orphaned-page规则命中的具体页面与责任源文件llmwiki next下一步建议当存在过期页面时它会自动推荐refresh --stale一个健康项目的status输出形如llmwiki status # ✓ Fresh: no stale or orphaned pages # ✓ State: ok若出现State: missing — run llmwiki compile或State: corrupt说明状态文件有问题直接跳到第三节处理。更多细节见 docs/cli/status.mdx 与 docs/troubleshooting/faq.mdx。二、过期页面Stale Pages与孤儿页面检测与一键修复核心机制每个 wiki 页面在编译时都会记录「由哪些源文件生成 内容哈希」。之后每次执行命令llmwiki 都会把记录的哈希与sources/磁盘现状对比——这就是源新鲜度追踪。两种新鲜度状态怎么区分Stale过期源文件还在但内容改了或多源页面中部分源被删除。页面还能读但可能已不代表最新资料。Orphaned孤儿生成该页面的所有源文件都被删除了页面已无法再生是清理候选。⚠️ 注意llmwiki query --save保存的问答页是生成答案永远不会被标记为过期。三步修复流程推荐顺序第 1 步查看哪些页面过期llmwiki lint # 关注规则名 stale-page 与 orphaned-page 的结果第 2 步预览修复计划零成本llmwiki refresh --stale --dry-run--dry-run只打印计划——哪些源会重编译、哪些孤儿页会被删除——不发生任何 LLM 调用不写盘。第 3 步执行修复llmwiki refresh --stale它只做三件事重编译「变更且拥有过期页」的源、清理孤儿页面纯文件操作、免 API Key、不碰无关页面。若所有过期页都是孤儿只是删源文件整个修复甚至不需要配置任何凭证。防止问题积累编辑期间保持llmwiki watch运行文件一保存就自动增量重编译过期页几乎不会堆积。完整的生命周期说明见 docs/troubleshooting/stale-pages.mdx。 小提示llmwiki view打开的 Viewer 会在页面元数据栏显示STALE / ORPHANED徽标顶部横幅显示整库新鲜度判定——不敲命令也能肉眼发现过期页。三、state.json 损坏或被新版本写入两种恢复路径.llmwiki/state.json是增量编译的账本带有 schemaversion字段。当它由更新版本的 llmwiki 写入比如同事用了新版本编译过当前构建会故意失败关闭并报错.llmwiki/state.json (version 3) was written by a newer llmwiki version (this build understands up to version 2). Upgrade llmwiki to read this project.这是设计好的安全行为宁可不读也不冒险误读或覆盖。你有两条路可走路线 A升级 llmwiki推荐npm install -g llm-wiki-compilerlatest升级后直接读取现有状态增量编译记录完整保留。路线 B重置状态文件保留备份llmwiki state reset # 先预览不做任何修改 llmwiki state reset --yes # 确认执行备份为 state.json.bak 后移除原文件 llmwiki compile # 从当前 sources/ 重建状态state reset --yes直接操作原始字节、从不解析状态文件因此即使文件「太新或损坏」也能可靠执行。原内容原子备份在.llmwiki/state.json.bak以后升级了版本还可以改回去。状态缺失或 JSON 损坏时lint和status会报告stateStatus: missing / corrupt并把所有页面标为unverifiedViewer 顶部出现损坏横幅。恢复方法统一是重新完整编译llmwiki compile官方恢复手册见 docs/troubleshooting/state-recovery.mdx新鲜度判定算法的源码位于 src/freshness/。四、Embedding 失败从报错到恢复的完整排查4.1 最常见ProviderUnavailableError跑compile时若报ProviderUnavailableError含义是找不到有效的 LLM 凭证——此时没有任何 LLM 调用发生、没有写入任何内容可安全重试。排查顺序默认 Anthropic 供应商确认ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN已设置二选一即可。若已配置本地 Claude Code~/.claude/settings.json的env块裸跑llmwiki compile应自动兜底读取。不想用 API Key可切换到免 Key 方案LLMWIKI_PROVIDERclaude-agent用本地 Claude Code 登录、ollama本地模型或copilot。4.2 query 检索不到相关内容llmwiki query的语义检索依赖嵌入索引.llmwiki/embeddings.bin或embeddings.json。索引缺失时会自动降级为纯词法BM25检索——能用但排序质量下降。常见原因当前供应商不支持嵌入copilot与claude-agent不暴露嵌入端点。claude-agent可设VOYAGE_API_KEY开启或显式指定LLMWIKI_EMBEDDING_PROVIDER如ollama免 Key。全新项目先跑一次llmwiki compile页面与嵌入会一起构建。⚠️ 若报embedding-store-unavailable说明索引文件存在但无法加载损坏。不要删除二进制索引去回退旧 JSON 快照——正确做法是执行llmwiki compile它会自动发现缺失向量并重建注意重建会消耗嵌入 API 额度隔离页除外。4.3 嵌入重试与隔离Quarantine机制嵌入生成失败时llmwiki 在.llmwiki/pending-embeddings.json中记录持久化重试预算同内容连续 5 次失败后页面被移入.llmwiki/quarantined-embeddings.json后续刷新跳过它让其他页面正常嵌入。内容一旦变化会以全新预算自动重试。排查信号看status输出的告警码embeddings-refresh-pending等待再次嵌入的页面embeddings-refresh-quarantined已耗尽重试、被隔离的页面修复供应商后的正确重置姿势① 确认没有 compile/refresh 在运行② 从两个标记文件中移除该页面条目重置全部则删除两个文件③ 重新llmwiki compile。注意只改嵌入配置不会清除隔离状态。4.4 切换嵌入后端会重建整个索引索引会记录生产它的供应商、模型与端点。修改LLMWIKI_EMBEDDING_PROVIDER/LLMWIKI_EMBEDDING_MODEL/ 端点后即使没有任何源变更下次 compile 也会重新嵌入全部合格页面有 API 成本。不同后端产出的向量不可比较重建前 query 会报告索引过时并退回词法排序。例外anthropic与claude-agent之间切换不重建二者走同一 Voyage 模型。五、性能调优清单让 compile 更快、检索更稳✅ 首次编译慢是正常现象所有源要走「概念提取 → 页面生成」两阶段流水线之后的编译是增量的未变更语料通常几秒完成。想进一步优化按此清单逐项检查环境变量默认值调优场景LLMWIKI_COMPILE_CONCURRENCY5冷启动/大批量刷新慢 → 调高上限 50可用--concurrency单次覆盖被供应商限流 → 调低LLMWIKI_PROMPT_BUDGET_CHARS200000stderr 频繁出现截断警告热门概念共享源过多→ 为大上下文模型调高如400000LLMWIKI_EMBED_BATCH_SIZE按供应商 64~256减少请求往返次数触到供应商上限则调低超上限会被钳制并告警LLMWIKI_EMBED_STRICT未设置CI 中设为1嵌入失败直接非零退出而非警告继续LLMWIKI_REQUEST_TIMEOUT_MS供应商内置openai 10 分钟 / ollama 30 分钟慢网关或本地模型超时 → 调大毫秒数LLMWIKI_STAGE_TIMING_FILE关闭设为绝对路径后compile/query 逐阶段追加 JSON 计时detect-changes、extraction、page-generation、embeddings 等精确定位慢在哪一步LLMWIKI_VERBOSE未设置任意非空值等价于--verbose查看分步进度与总耗时四条实用策略小步快跑大语料先用llmwiki quickstart 单个源跑通再增量加入其余源。换更快的模型设LLMWIKI_MODEL为供应商的轻量模型变体。大索引自动走二进制存储超过 64 MiB 的 JSON 上限后自动切换embeddings.bin无需手动干预上限512 MiB 文件 / 10 万条记录。编辑期开 watchllmwiki watch实时增量重编译避免积压。完整变量参考含调试开关LLMWIKI_DEBUG见 docs/configuration/environment-variables.mdx。六、症状速查表症状最可能原因快速修复ProviderUnavailableErrorAPI Key 未设置配置ANTHROPIC_API_KEY或切换免 Key 供应商lint报stale-page源文件内容已变更llmwiki refresh --stale先--dry-runstatus报State: corruptstate.json 不可读llmwiki compile重建报错「written by a newer llmwiki version」新版本写过状态升级 llmwiki或llmwiki state reset --yesquery 结果相关性差嵌入索引缺失配置LLMWIKI_EMBEDDING_PROVIDER后 compileembedding-store-unavailable索引损坏llmwiki compile自动重建索引compile 首次极慢全量两阶段编译属正常后续用LLMWIKI_COMPILE_CONCURRENCY提速CI 中嵌入静默失败非严格模式只告警设LLMWIKI_EMBED_STRICT1七、相关文档与源码路径故障排查 FAQdocs/troubleshooting/faq.mdx过期页面检测与修复docs/troubleshooting/stale-pages.mdx状态版本恢复手册docs/troubleshooting/state-recovery.mdx环境变量全参考嵌入重试与隔离、存储上限docs/configuration/environment-variables.mdxstatus 命令输出字段docs/cli/status.mdx新鲜度追踪实现src/freshness/lint 规则实现src/linter/ 记住排障口诀先看status定方向再用lint定页面dry-run预览后才动手compile兜底一切状态问题。【免费下载链接】llm-wiki-compilerThe knowledge compiler. Raw sources in, interlinked wiki out. Inspired by Karpathys LLM Wiki pattern.项目地址: https://gitcode.com/gh_mirrors/ll/llm-wiki-compiler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考