OpenAI Responses API 写作任务怎么用 metadata 追踪

准备

先确定一套稳定的任务标识。建议至少准备文章 ID、客户 ID、发布批次和任务类型，例如生成、改稿或审核。metadata 适合保存结构化索引，不要把整段提示词、正文或敏感资料塞进去。

资料显示，Responses API 的 metadata 最多可设置 16 组键值对，键最长 64 个字符，值最长 512 个字符。接口支持在创建响应时传入 metadata。为了让应用侧记录完整，仍建议同步保存输入、请求参数、response_id、状态和最终正文。关于响应记录归档，可参考OpenAI Responses API 写作结果怎么保存和复用响应记录。

分步操作

1. 设计字段。固定字段名，例如 article_id、client_id、batch_id 和 task_type。字段名一旦投入批量流程，尽量不要频繁改名。
2. 生成任务标识。在调用接口前，由业务系统创建内部任务 ID，并把它与文章记录、操作人和当前状态关联。
3. 调用 Responses API。将字段值作为字符串放入 metadata，同时传入模型、instructions 和 input。示例使用 Python SDK：

from openai import OpenAI

client = OpenAI()

article_id = "article_20260828_001"
task_id = "task_20260828_001"

response = client.responses.create(
    model="gpt-4o",
    instructions="根据输入资料写出结构清晰的文章草稿。",
    input="请生成一篇关于内容流程管理的入门文章。",
    metadata={
        "task_id": task_id,
        "article_id": article_id,
        "client_id": "client_acme",
        "batch_id": "batch_20260828_a",
        "task_type": "draft",
    },
)

print(response.id)

4. 保存响应 ID。收到响应后，立即把 response.id 写入任务表，并记录请求时间、模型、metadata、响应状态和正文提取结果。
5. 更新业务状态。请求成功不等于文章可以发布。建议把任务状态拆成 created、generated、reviewing 和 published，由应用自己的验收流程推进。
6. 按标识排查。后台查询时先按内部 task_id 或 article_id 找到任务，再使用 response_id 获取对应响应。metadata 是关联线索，不应替代自己的任务数据库。

可复制模板或示例

下面是一套适合 AI 写作任务追踪的字段模板。值全部使用字符串，方便统一序列化和后续检索。

metadata = {
    "task_id": "task_唯一任务号",
    "article_id": "article_文章号",
    "client_id": "client_客户号",
    "batch_id": "batch_发布批次",
    "task_type": "draft_or_rewrite",
    "source_version": "资料版本号",
}

若一次任务需要多轮改稿，可以每轮创建独立 task_id，并在自己的任务表中保存 parent_task_id、previous_response_id 和版本号。这样既能定位当前响应，也能还原修改链路。不要假设 metadata 会自动替你保存完整的业务状态，状态变更仍应由应用写入数据库。

翻车怎么改

常见故障：批量任务都显示成功，但无法判断响应属于哪篇文章。原因通常是调用时没有传 metadata，或者所有任务复用了同一个固定值，导致关联字段失去区分度。修正动作是让业务系统在发起请求前生成唯一 task_id，并至少写入 article_id、batch_id 和 task_type；同时把同一份 metadata 保存到本地任务表。

常见故障：metadata 提交时报参数校验错误。原因可能是字段数量、键长度或值长度超出资料中列出的限制，也可能把数字、对象等未统一转换为字符串。修正动作是调用前执行字段数量、键名长度和值长度检查，并将所有值显式转换为字符串。

常见故障：响应 ID 有了，但正文和审核状态对不上。原因是只保存了 API 返回的 ID，没有保存输入、模型、版本和本地状态。修正动作是将 response_id 作为外部响应索引，与任务表中的输入摘要、模型、metadata、状态和最终正文放在同一条记录中。

完成前检查

• 每个请求是否都有唯一且可回查的 task_id。
• article_id、batch_id 和 task_type 是否在 metadata 与本地任务表中一致。
• metadata 是否符合最多 16 组键值对、键最长 64 个字符、值最长 512 个字符的限制。
• 是否保存了 response_id、模型、输入摘要、响应状态和最终正文。
• 发布前是否确认正文完整、任务状态已通过审核，并且能从文章记录反查到对应响应。