LLM 日志与排障#

OpenAI Provider 可把每个翻译批次的模型输入、模型输出、校验和持久化状态写成普通文本日志。 这些日志适合人工审查，也可以交给 AI 编码工具判断问题发生在哪个环节。

#开启或关闭日志

日志默认关闭。需要排障或审查时，只需配置 provider.logging：

aiI18n({
  sourceLang: 'zh-CN',
  locales,
  provider: {
    translator: openAI({
      baseURL: process.env.AI_BASE_URL!,
      apiKey: process.env.AI_API_KEY,
      model: process.env.AI_MODEL!,
    }),
    logging: true,
  },
});

省略或设置 provider.logging: false 时，当前 Vite 开发服务器或构建进程不会创建或追加日志。 它也不会创建默认的 logs/ 目录。翻译、提取、缓存和持久化照常执行。

logging: true 写入 Vite 项目根目录下的 logs/。也可以直接用字符串指定目录：

provider: {
  translator,
  logging: 'diagnostics/llm', // 相对 Vite root
}

相对字符串基于 Vite root 解析。绝对字符串保持不变。空字符串或只包含空白的字符串是无效配置，插件会在启动时报告双语错误。 日志开关没有 OpenAI Provider 级的第二套优先级。

#日志文件生命周期

一个 openAI() Translator 实例在每个已解析目录中使用一个日志文件。文件名包含本地日期、时间、PID 和进程序号：

2026-08-06_13-46-44-834-p65013-1.log

• 普通构建每次创建新的 Translator，因此通常生成一个新文件。
• 同一开发服务器、HMR 或构建监听进程复用 Translator，后续批次继续追加到同一文件。
• 日志写入失败只警告一次，不会让翻译或构建失败。

#按 batchId 阅读

同一翻译批次的每个日志块都带有相同 batchId。排障时先找到失败文案对应的 REQUEST 或 BATCH FAILED，再沿相同 ID 阅读：

BATCH SCHEDULED
REQUEST
RESPONSE
VALIDATION
STATE APPLIED
PERSISTED

并发批次可能交错写入同一个文件。不要只按相邻行判断请求与响应，始终按 batchId 关联。

#常见定位方式

• 有 REQUEST、没有 RESPONSE：优先检查超时、网络、认证、模型名与服务端错误。
• 有 RESPONSE、随后 BATCH FAILED：检查返回格式、目标语言和占位符。
• 有 VALIDATION、没有 STATE APPLIED：检查终端中是否有状态应用错误。
• 有 STATE APPLIED、没有 PERSISTED：结合构建/开发服务器终端错误检查目录权限、文件冲突或存储失败。
• 已有 PERSISTED 但页面不更新：检查当前语言和语言加载状态，并刷新开发页面确认。

给 AI 编码工具排障时，请提供相关日志文件。要求它先按 batchId 汇总上述阶段，再结合终端错误判断。 日志记录模型与 SDK 提供的审查信息，不是逐字节 HTTP 抓包。

#安全与 Git 忽略

日志包含待翻译业务文案、完整提示词和模型输出，不应提交到版本库。 默认目录的忽略规则见 生成文件与 Git。 使用自定义目录时，也要忽略该目录。

Provider 会脱敏显式 API key。OpenAI SDK 会脱敏常见认证 Header。 提交或分享日志前仍应人工检查业务敏感信息。