跳到主要内容

故障排除

💡TL;DR

大多数 Notemd 问题可归为四类：API 关键问题、网络连接问题、身份验证错误（401/403）以及速率限制问题（429）。 内置的连接测试和诊断面板能够快速定位根本原因。本页面涵盖了所有常见的错误信息、其成因及解决方法。对于未列出的问题，请将诊断结果附上后通过 GitHub Issues 进行报告。

这是Obsidian AI知识管理指南的一部分。

概览​

Notemd 依赖于外部服务——即 LLM 提供商和搜索 API 服务——因此大多数问题都源于插件本身之外。设置中的诊断面板可以以结构化的方式展示上一次 API 调用的相关信息，包括请求 URL、响应状态以及错误内容。在进一步排查之前，请务必先查看该面板。

工作原理：诊断功能​

连接测试​

每个提供商配置部分都有一个**“测试连接”**按钮。点击该按钮会发送一个最简的 API 请求（通常是模型列表或简短的补全内容），并反馈成功状态或具体的 HTTP 错误信息。这是验证您的 API 密钥及基础 URL 是否正确的最快方法。

诊断面板​

设置 --> Notemd --> 诊断 显示：

字段内容
上一个提供商上次调用的是哪个提供商
最新型号上一个被调用的是哪个模型
最后状态HTTP 状态码或传输错误
上一个错误来自 API 的原始错误信息
上一个请求 URL上一次请求的完整内容 URL（已删除 API 关键字）
上次响应的正文内容响应体被截断（前500个字符）

在 GitHub 上报告问题时，请复制完整的诊断输出。

常见错误​

API 密钥无效或丢失​

症状： HTTP 返回 401 错误或“提供的 API 密钥不正确”

原因： API 键缺失、包含空白字符，或属于其他提供商。

修复：

  1. 验证该密钥没有前后空格。
  2. 确认密钥与所选的提供商匹配（OpenAI 类型的密钥无法与 Anthropic 使用）
  3. 检查您的账户是否有余额或有效的订阅。
  4. 点击**“测试连接”**以进行验证

网络/连接错误​

症状： ERR_CONNECTION_REFUSED, ERR_TIMED_OUT, Socket hang up, Network request failed

原因： 您的机器无法访问 API 接口。

修复：

  1. 检查您的互联网连接。
  2. 如果在代理或防火墙后面，请确认 API 域名未被屏蔽
  3. 针对 Ollama：确认 ollama serve 正在运行（ollama list 应返回模型信息）
  4. 关于 LMStudio：确认服务器正在 localhost:1234 上运行。
  5. 尝试使用其他传输方式——移动用户应确保 requestUrl 传输功能处于启用状态
  6. 启用 enableStableApiCall 以在临时错误时自动重试

403 禁止访问​

症状： HTTP 返回 403 错误

原因： 您的 API 密钥有效，但没有访问所需资源的权限。

修复：

  1. 某些模型需要特殊权限（例如，通过 Azure 使用的 GPT-4 需要指定部署名称）。
  2. 某些提供商会根据套餐等级限制模型使用——请查看您的账户。
  3. 可能会受到地区限制（某些中国服务商会屏蔽国际 IP，反之亦然）。
  4. 验证模型名称的拼写是否正确（例如，当迷你模型是您计划允许的全部内容时，应为 gpt-4o 而非 gpt-4o-mini）

速率限制（429）​

症状： HTTP 返回 429 错误或“速率限制已达到上限”

原因： 在短时间内请求过多。

修复：

  1. 将 batchConcurrency 转换为 1 或 2
  2. 请等待几分钟后再尝试。
  3. 请查阅您所在套餐等级的提供商速率限制相关文档。
  4. 启用 enableStableApiCall 以实现带退避的自动重试
  5. 考虑更换为额度更高的服务提供商（DeepSeek, Ollama）。

未找到模型。​

症状：“未找到模型”或 HTTP 404 错误。

原因： 所选提供方上不存在该模型名称。

修复：

  1. 点击**“获取模型列表”**，即可查看您的提供商提供的所有可用模型。
  2. 有些型号名称会随时间变化——请在供应商的文档中确认当前名称。
  3. 针对 Ollama：运行 ollama list 可查看已拉取的模型；仅下载过的模型可用

未生成链接/概念​

症状： 命令已运行，但未产生任何输出

原因： LLM 返回了空响应或无法解析的响应。

修复：

  1. 查看诊断面板以获取实际的 LLM 响应。
  2. 试试功能更强的模型（一些小型模型在处理结构化输出时会有困难）。
  3. 确保该备注的内容足够丰富（超过50个字）。
  4. 检查您的自定义提示语中是否存在相互矛盾的指令。
  5. 暂时禁用同义词抑制功能，看看它是否过滤得过于严格。

Doubao 缺少端点 ID​

症状： 使用 ByteDance Doubao 提供商时出现错误

原因： Doubao 需要的是 Ark 端点 ID（格式：ep-xxxxxxxx-xxxx-xxxx），而非模型名称。

修复方法： 用 Volcengine 控制台中的实际端点 ID 替换默认的占位符模型。

配置​

诊断设置位置用途
测试连接设置 --> 提供商部分验证 API 密钥及连接状态
获取模型列表设置 --> 提供商部分确认哪些型号是可访问的
enableStableApiCall设置 --> 高级选项启用带退避的重试功能
batchConcurrency设置 --> 批处理控制并行度以避免速率限制

如何报告问题​

如果您的问题不在上述范围内：

  1. 打开设置 --> Notemd --> 诊断
  2. 复制完整的诊断输出
  3. 在 github.com/Jacobinwwey/obsidian-NotEMD/issues 处创建一个 GitHub Issue。
  4. 包含：Obsidian版本、Notemd版本、提供商、型号、诊断输出以及复现步骤
  5. 从所有共享日志中删除您的 API 密钥

后续步骤​

编辑此页
最后由 aliyun1121003339 于 更新