WorkBuddy 模型的输出格式问题通常表现为：同一个接口有时候返回纯文本，有时候返回 JSON，有时则夹带解释性前缀。要让下游系统可靠消费模型结果，必须在请求侧做好格式声明，而不是只依赖提示词里写一句请返回 JSON。本文会从参数配置、Schema 定义、提示词配合与校验兜底四个方面说明具体设置方法。
一、输出格式失控的常见原因
WorkBuddy 模型在默认情况下会根据训练数据和采样策略生成内容，它并不会天然保证返回纯 JSON、固定列数的表格或者某种特殊结构。即使提示词中明确要求返回 JSON，模型仍然可能输出类似以下内容：一个友好的开头说明，接着是 JSON 代码块，最后再加上一句补充解释。这种结果对阅读者友好，但对程序解析非常不友好。
更常见的情况是，同一个提示词在不同请求中会得到不同形态的输出。比如一次返回紧凑 JSON，一次返回带注释字段的 JSON，还有一次可能直接返回自然语言。原因在于模型每次生成都会重新选择表达路径，提示词只是软约束，无法像参数一样强制限定格式。因此，若业务系统需要稳定消费模型结果，就必须使用输出格式控制能力，而不是只靠提示词文本。
输出格式失控还会造成解析链路中的连锁问题。例如订单信息提取任务中，如果模型把金额写成字符串而不是数字类型，后续数据库写入可能失败；如果字段名中英文混用，下游映射也会出错。设置输出格式的实质，是把模型的生成空间从无限文本压缩到满足业务契约的结构化空间。
二、使用 response_format 参数与 JSON Schema 约束
WorkBuddy 的开放接口提供 response_format 参数，用于声明模型返回内容的类型。最常用的配置方式是设置为 json_schema，并通过 json_schema 字段传入一份 JSON Schema。这样模型不仅知道要返回 JSON，还能按照 Schema 中的字段名、类型、枚举值和必填项生成内容。
下面是一个完整的 Python 调用示例，演示如何从合同文本中提取甲方、乙方、金额和币种，并将输出强制约束为指定结构。
import openai
client = openai.OpenAI(
api_key="your-workbuddy-key",
base_url="https://api.workbuddy.ipipp.com/v1"
)
response = client.chat.completions.create(
model="workbuddy-pro",
messages=[
{"role": "system", "content": "你是一个数据提取助手，只输出结构化结果。"},
{"role": "user", "content": "从合同文本中提取甲方、乙方和金额。"}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "contract_extract",
"strict": True,
"schema": {
"type": "object",
"properties": {
"party_a": {"type": "string"},
"party_b": {"type": "string"},
"amount": {"type": "number"},
"currency": {"type": "string", "enum": ["CNY", "USD", "EUR"]}
},
"required": ["party_a", "party_b", "amount", "currency"],
"additionalProperties": False
}
}
}
)
print(response.choices[0].message.content)
这份 Schema 的关键点有三个。第一，type 设置为 object，表示返回顶层必须是 JSON 对象。第二，required 数组列出了所有必须出现的字段，模型不能遗漏任何一项。第三，additionalProperties 设置为 false，禁止模型自行添加未定义的字段，这能显著降低字段漂移风险。
如果业务只需要普通 JSON，而不关心具体字段结构，也可以将 response_format 的 type 设置为 json_object。这种模式比 json_schema 更宽松，但仍能保证模型输出合法 JSON。不过建议生产环境优先使用 json_schema，因为字段级约束才能真正避免解析失败。
三、提示词模板与后处理双保险
参数约束能够解决大部分格式问题，但并不意味着提示词可以随意编写。稳定的做法是先通过系统提示词明确任务边界，再在用户提示词中说明输出要求。提示词和 response_format 应该保持一致，避免模型接收到互相冲突的指令。例如 Schema 要求金额是数字类型，提示词却写输出金额保留两位小数并带货币符号，这会让模型陷入矛盾。
即使配置了 json_schema，后端仍然需要做一层轻量后处理。原因在于网络层返回的 content 字段通常是字符串，而不是解析好的对象。你需要将字符串反序列化为 Python 字典，并验证关键字段是否齐全。下面是一段可复用的解析函数。
import json
def parse_workbuddy_output(raw_text: str):
# 去除可能的围栏标记和解释文字
cleaned = raw_text.strip()
if cleaned.startswith("```"):
cleaned = cleaned.split("\n", 1)[1]
if cleaned.endswith("```"):
cleaned = cleaned.rsplit("\n", 1)[0]
try:
data = json.loads(cleaned)
except json.JSONDecodeError as e:
raise ValueError(f"返回内容不是合法 JSON: {e}") from e
return data
这段逻辑同样适用于 json_object 模式，因为部分模型仍可能在 JSON 前后添加 Markdown 围栏标记。先清理首尾不可见字符，再去掉可能的代码块边界，最后执行 JSON 解析，可以把格式容错率提升一个层级。对于要求极严的业务，还可以在解析后用 JSON Schema 校验库再次验证，形成参数约束、提示词约束、代码校验三道防线。
值得一提的是，后处理不应掩盖模型输出格式的严重问题。如果解析频繁失败，应当回到请求侧调整 Schema 或提示词，而不是无限增加清理规则。把问题解决在生成源头，比在消费端不断打补丁更可靠。
四、常见错误与排查思路
第一个常见错误是只修改提示词，不设置 response_format。这种方式在简单任务中可能有效，但随着输出结构变复杂，成功率会明显下降。排查时可以先观察失败样本：如果模型输出的是合法 JSON 但字段不稳定，说明需要补 Schema；如果模型输出包含解释文字，说明需要开启严格模式或调整提示词。
第二个常见错误是 Schema 定义过严。某些开发者为了安全，把所有字段都设为必填，并禁止额外属性。当输入文本本身缺失某些信息时，模型可能为了满足必填约束而编造数据。正确做法是根据业务真实性评估每个字段是否必须存在，可选字段不应列入 required，也可以为缺失值预留空字符串或空对象等默认形态。
- 返回被 Markdown 围栏包裹：检查是否使用
json_object模式，并配合后处理清理代码块标记。 - 字段名与 Schema 不一致：检查提示词中是否出现了其他命名，或 Schema 中是否缺少
additionalProperties限制。 - 数字类型被返回为字符串：确认提示词没有要求保留格式符号，同时检查 Schema 中该字段是否为
number或integer。 - 多轮对话中格式漂移：在每轮请求中都携带相同的
response_format，不要只在首轮声明一次。
最后还需要关注模型版本差异。不同版本对 json_schema 的支持程度可能不同，升级模型后应重新验证输出格式是否仍然稳定。建议维护一份固定测试集，覆盖常见输入场景，并在每次调整提示词、Schema 或模型版本后执行格式校验。只有把格式设置当作正式工程契约来维护，WorkBuddy 模型的输出才能真正嵌入自动化流程。
WorkBuddy模型输出格式JSON Schema修改时间：2026-08-30 19:17:33