DeepSeek-V4.1-Flash-1017 输出跑偏——先收紧提示词再考虑解析兜底

DeepSeek-V4.1-Flash-1017 这类模型在“期望返回 JSON、实际返回一段带说明文字或被 ``` 包裹的文本”时，解析层抛异常是最常见的故障形态。处理顺序建议是：先把失败样本捞出来确认包裹形态，再把输出格式约束写进系统提示并配一个示例，然后用固定输入重复调用判断是偶发漂移还是稳定跑偏，最后才在解析层加剥壳与失败上报作为兜底。反过来做——先加一堆正则容错——通常会把提示词本身的问题掩盖掉，后面很难判断改动到底有没有用。

结构化输出解析失败时，先不要动解析代码。抓一条原始返回，判断是代码块包裹、前后夹说明文字还是字段缺失；前两种优先改系统提示里的格式约束与示例，字段缺失则检查字段名、类型和空值约定。用同一输入重复调用若干次，区分偶发漂移与稳定出错，再决定是否加剥壳。剥壳只用于避免流程中断，不改变模型行为，需同时记录剥壳命中与解析失败次数，持续观察后再判断提示词改动是否生效。

抓一条失败样本看清包裹形态

第一步不是改代码，是把失败的原始返回原样留下来。很多团队在日志里只记了 json.decoder.JSONDecodeError 和一段被截断的文本，事后根本看不出模型到底多返回了什么。建议在调用处把原始字符串完整落盘或写进日志字段，不做 strip、不截断、不做二次转义，同时带上 prompt 版本号和请求 id，便于回溯。

形态分类可以按下面的判定顺序走，从首字符开始看，避免主观描述：

首字符是 ``` 或以 ```json 开头：代码块包裹，模型把答案当成了“演示代码”。
首字符不是 { 但文本中存在 {：前后夹了说明文字，如“好的，以下是结果：”。
整体是合法 JSON 但字段名对不上、类型不对、数组套了一层对象：字段缺失或结构漂移，属于提示词约束不清，不是解析问题。
一次返回里出现多段 JSON：模型在给出多个候选，通常出现在“如果……则……”这类分支描述较多的提示词里。

判定依据建议写成一个小函数固化下来，对每条样本打一个形态标签，后续统计才有统一口径。形态标签和原始返回放在同一行日志里，比事后再靠人眼看要可靠。

把输出格式约束写进系统提示并给一个示例

含糊的描述是跑偏的主要来源。“请以 JSON 格式返回”这种写法，模型完全可以用“以下是 JSON：”开头，或者加上代码块，因为这两者在人类语境里都算“JSON 格式”。约束段落要写成可判定的要求：字段清单、每个字段的类型、禁止项、空值怎么写。

# 修改前（含糊）
请以 JSON 格式返回结果。

# 修改后（可判定）
输出必须是一个 JSON 对象，且满足：
1. 第一个字符是 {，最后一个字符是 }，前后不得有任何说明文字。
2. 不要使用 Markdown 代码块，不要加注释，不要输出多个候选。
3. 字段固定为：title(string)、summary(string)、tags(array[string])、score(number)。
4. 字段缺失时写 null，不要省略字段，不要自造字段名。

示例的选取原则是“最小但覆盖全部字段”：字段名必须和真实解析代码一致，最好带上一个容易出错的点，比如数组字段或嵌套对象，让模型看到正确形态。不建议在提示里放一个带解释的错误示例，模型容易把解释文字也一起模仿出来。示例本身也必须是纯 JSON，不加代码块围栏。

DeepSeek-V4.1-Flash-1017 输出跑偏——先收紧提示词再考虑解析兜底

改完之后不要立刻宣布问题解决，先拿同一批失败样本的输入重跑一遍，看形态标签是否从“代码块包裹”变成“合法 JSON”。这一步的可核验点很直接：日志里 strip_mode 为 none 且解析成功的比例有没有变化。

固定输入重复调用看跑偏是否稳定

同一个输入，一次成功一次失败，说明是采样层面的漂移；每次都失败，说明提示词或字段定义有结构性问题，靠重复调用救不回来。建议固定 1 条代表性输入，重复调用 5 到 10 次，参数保持一致（模型版本、温度、最大输出长度都用同一组值），把每次的原始返回存成独立文件。

差异对比不用做复杂 diff，按三个层次看就够：

形态层：每次的形态标签是否一致，是否集中在某一种包裹方式。
字段层：字段集合、字段类型、数组长度是否稳定。
内容层：同一字段的取值差异是否影响下游逻辑。

如果加入温度之类的采样参数，最好也记录在日志里，否则容易把“参数不同”误判成“模型不稳定”。

在解析层补上剥壳与失败上报

提示词收紧之后仍然会有零星波动，这时才值得加一层轻量兜底。剥壳的原则是“只处理外层包裹，不改动内部结构”，并且必须记录命中次数——否则你永远不知道是提示词起作用了，还是剥壳一直在兜着。

import json, re

FENCE = re.compile(r"^\s*```[a-zA-Z0-9_-]*\s*\n(.*?)\n\s*```\s*$", re.S)

def extract_payload(raw: str):
    """返回 (候选文本, 剥壳方式)，方式取值 fence / brace / none"""
    text = raw.strip()
    m = FENCE.match(text)
    if m:
        return m.group(1).strip(), "fence"
    start, end = text.find("{"), text.rfind("}")
    if start != -1 and end > start:
        return text[start:end + 1], "brace"
    return text, "none"

def parse_structured(raw: str, meta: dict):
    candidate, mode = extract_payload(raw)
    try:
        data = json.loads(candidate)
    except json.JSONDecodeError as err:
        log.warning("structured_parse_failed", extra={
            "raw": raw,                 # 原样保留，不截断
            "strip_mode": mode,
            "error": str(err),
            "request_id": meta["request_id"],
            "prompt_version": meta["prompt_version"],
            "model": meta.get("model"),
        })
        return {"ok": False, "strip_mode": mode}
    return {"ok": True, "data": data, "strip_mode": mode}

两点需要注意。用首尾大括号截取时，如果返回里本身有多个对象，rfind 可能截到错误区间，所以这种兜底只能用于单对象场景；解析成功之后还要做一次字段校验，字段缺失应该单独记为 schema_invalid，不要和 json_invalid 混在一起统计。剥壳是避免流程中断的临时措施，不解决模型行为问题。

把解析失败率接进日志持续观察

日志至少要能回答三个问题：失败了没有、怎么失败的、是不是同一个提示词版本。建议的字段包括 request_id、prompt_version、model、strip_mode、parse_result（ok / json_invalid / schema_invalid）、raw_length，必要时附原始返回文件路径。

统计口径要提前定死，否则数字没意义。分母建议只算“期望结构化输出的调用”，把闲聊类、试探类请求排除；分子按失败类型拆开，剥壳后成功单独算一类。如果剥壳后成功率很高而原始解析成功率没变，说明提示词改动并没有起效，只是被兜底遮住了。

观察周期建议按天看，至少覆盖一个业务周期，结合调用量的波动一起看，不要用单日样本下判断。停止条件可以设成两种：一是提示词改动上线后，原始解析失败数没有回落趋势，那就回滚或重写约束段落；二是剥壳命中与彻底失败都降到可接受区间并保持稳定，此时可以停止逐条人工看样本，改为按比例抽样，只保留日志告警。