Gemini API 请求日志定位写作异常

先定义一条可追溯的任务记录

日志的目标不是保存所有内容，而是让同一任务可以从提交追到最终草稿。每条记录应使用内部任务 ID 关联；密钥、访问令牌、用户隐私内容和不需要排查的完整资料不应直接写入普通日志。

• 任务信息：任务 ID、批次 ID、创建时间、重试次数和执行环境。
• 请求信息：模型标识、接口类型、请求参数、提示词版本和输入内容摘要或受控存档引用。
• 响应信息：HTTP 状态、响应 ID、原始响应的受控存档位置、耗时和可提取的文本或工具调用片段。
• 应用结果：解析状态、草稿 ID、正文长度、校验错误和最终处理状态。

官方更新记录显示，Gemini API 的日志与数据集工具已推出；对于受支持的 Interactions API 调用，开发者日志可在 AI Studio 控制台查看。控制台记录适合辅助核对，业务系统仍应保留自己的任务关联和处理结果。

按请求生命周期写入日志

1. 生成任务 ID，并在进入队列前记录文章目标、提示词版本和资料版本。
2. 调用前记录模型标识、接口类型、配置对象的允许字段及输入摘要；不要记录 API 密钥。
3. 收到响应后先保存状态码、耗时和原始响应的受控引用，再执行正文提取或工具调用处理。
4. 解析完成后记录提取到的字段、正文长度和校验结果；失败时保存错误码与失败阶段。
5. 写入草稿或发布队列后记录目标对象 ID，形成任务 ID 到文章 ID 的闭环。

{
  "task_id": "write-20260911-018",
  "model": "configured-model-id",
  "prompt_version": "article-v4",
  "request_status": "sent",
  "response_status": "received",
  "parse_status": "failed",
  "body_length": 0,
  "error_code": "BODY_NOT_FOUND"
}

字段名可按现有系统调整，但状态要区分“接口未成功”“接口成功但响应不符合预期”和“应用处理失败”。这能避免把所有异常都归为模型问题。

用一条异常任务完成对照

例如，编辑反馈某批任务显示成功但草稿正文为空。先用任务 ID 找到请求记录：若请求中的输出规则和资料版本正确，且响应存档中已有可用正文，则问题在提取、映射或保存环节；若响应中没有正文，再查看停止原因、响应结构和工具调用结果。使用 Interactions API 且出现结构读取问题时，可结合响应字段迁移检查方法核对应用是否仍在读取旧字段。

若请求记录显示模型标识或提示词版本与预期不一致，应先修正任务配置，再用同一份固定样本重新执行。不要直接拿新任务覆盖旧日志，否则无法比较异常前后的差异。

常见故障怎样排查和修正

• 常见故障：接口返回成功但正文为空。原因：应用从错误的响应字段提取文本，或仅处理了某一种输出项。修正动作：保存原始响应引用，逐层确认候选输出，再为缺少正文设置明确失败状态。
• 常见故障：工具调用后任务停在处理中。原因：应用没有记录调用 ID、没有回传结果，或回传结果与任务不匹配。修正动作：把调用 ID、工具名、执行状态和回传时间写入同一任务链路，并对超时任务标记待人工处理。
• 常见故障：同一任务出现两篇相近草稿。原因：超时后盲目重试，未使用任务 ID 判断是否已完成。修正动作：重试前查询既有处理状态；为写入草稿增加幂等键。
• 常见故障：异常无法复现。原因：日志只保留错误文本，没有保存模型、配置和提示词版本。修正动作：补齐版本字段，并保留经脱敏后的固定测试样本。

发布前检查清单

• 任务 ID、批次 ID 与草稿 ID 可以互相查询。
• 日志中没有 API 密钥、令牌或不应暴露的原始资料。
• 每次调用均记录模型、接口类型、提示词版本、状态、耗时和处理结果。
• 正文为空、结构不合法和工具未回传均会进入明确错误状态，不会自动发布。
• 固定异常样本已验证：能区分请求问题、模型响应问题和应用处理问题。
• 编辑在发布前已确认正文长度、标题字段和最终草稿内容与任务目标一致。