Beam 接进已有服务后，请求报错或返回空，先别调 temperature、top_p 这类参数，它们不解决字段名、类型、超时和返回层级问题。先把客户端实际发出的请求体、服务端返回的原始响应体和一次长输出真实耗时对齐，再决定是否调参。下面按抓报文、核字段、看响应、设超时、按错误分流五步走，每一步都给出可验证动作。

接 Beam 到已有服务时，判断优先级建议是：请求字段与返回结构 > 超时与重试 > 输出参数。先在客户端打印请求体和未解析响应体，对照实际服务文档逐项核对字段名、取值类型和内容层级；再用一次长输出观察实际耗时来设置超时。只有确认请求能稳定返回、错误能按连接、鉴权、字段、超时四类分流后，调参才有可比较的基线。字段文档以你接入的具体服务为准，不要照搬示例键名。

抓一次失败请求的原始报文

请求失败时，第一个可靠信息是客户端实际发出去的内容，而不是你代码里想发的内容。打印请求体建议放在 HTTP 调用前一行，确保序列化后的最终字符串被输出；如果用 requests，可以在 post 前 log 出 body；如果用 curl，用 -v 或 `--trace-ascii` 保存完整报文；服务端侧若有网关日志，也先看它收到的 body 长度和关键键名。

# 在调用前打印最终请求体，注意不要打印密钥
import json, logging
payload = {...}
logging.warning("beam request body: %s", json.dumps(payload, ensure_ascii=False))
resp = session.post(url, json=payload, timeout=(5, 60))
logging.warning("beam raw response: %s", resp.text[:2000])

重点看的字段：model 是否写成服务要求的名称，messages 是否为数组且每个元素含 role 和 content，max_tokens 一类限制字段是否传成字符串，stream 是布尔值还是字符串。抓包时同样先看 body 里这几个键的拼写和类型，不要急着看响应。日志中如果 body 被截断，先看长度和头部键名，再决定是否完整打印。

逐项核对字段名与取值类型

字段拼写和类型是接入阶段最常见的报错来源。通常需要按实际服务文档逐项对照，而不是按记忆或另一个平台的字段名套用。常见字段包括：模型名、消息数组、最大生成长度、流式开关。模型名要区分大小写和分隔符；消息数组一般要求 role 和 content 成对出现，content 可能是字符串也可能是分段数组，这取决于具体服务；最大生成长度字段名可能是 max_tokens、max_output_tokens 或别的名字，类型通常是整数；流式开关通常是布尔值，传字符串 "true" 可能被拒。

{
  "model": "服务文档中的模型标识",
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "max_tokens": 128,
  "stream": false
}

核对方法：把文档里的字段表逐行抄到本地检查列表，每行写字段名、类型、是否必填、取值示例；再用同一份检查列表对照打印出来的请求体。遇到 400 类错误，先看错误信息里提到的字段名，回到检查列表改拼写或类型，再复测一次，不要同时改多个字段。

打印原始响应体确认取值路径

返回空或解析失败时，先不要假设内容在 choices[0].message.content 或 output.text。不同服务、不同版本的响应层级可能不同。稳妥做法是先把未解析的响应体输出出来：用 resp.text 而不是 resp.json()，同时记录 HTTP 状态码和 Content-Type。如果响应体很长，先打印前 1000 到 2000 个字符，确认它是 JSON 对象、数组还是纯文本；再逐步用解析后的对象打印顶层键名。

print(resp.status_code, resp.headers.get("Content-Type"))
print(resp.text[:2000])

data = resp.json()
print(type(data))
print(data.keys() if isinstance(data, dict) else len(data))

# 找到候选内容后，再打印路径和类型
print(type(data.get("content")), data.get("content"))

判断内容字段层级时，先看顶层有没有 data、result、output、choices 这类包裹键；再看下一层是对象还是数组；最后找承载文本的字段。确认路径后再把它写进解析代码，并加一层空值判断：路径不存在时返回原始响应体，避免直接抛异常。

按实际耗时设置超时与重试

长输出被客户端提前掐断，通常不是模型没生成完，而是超时设得太短。超时配置位置因客户端而异：Python requests 在 post 的 timeout 参数，curl 有 `--max-time` 和 `--connect-timeout`，HTTP 客户端库一般在 session 或 client 初始化处。建议把连接超时和读取超时分开放：连接超时短一些，读取超时按一次长输出的实际耗时留出余量。

# 连接超时 5 秒，读取超时先给 120 秒，再按实测调整
resp = session.post(url, json=payload, timeout=(5, 120))

# curl 分开控制连接和总时长
# curl `--connect-timeout` 5 `--max-time` 180 -X POST ...

观察一次长输出实际耗时，可以在调用前后各打一条时间日志，或者用 curl 的 -w 输出 time_total。记录的是包含排队、生成和网络传输的总时长，不是模型内部耗时。重试次数建议先不自动重试，等超时和错误分类清楚后再决定；如果加，通常只对连接失败和部分超时重试，且要限制次数并加间隔，避免把字段错误或鉴权错误也重试一遍。

按错误类型分流处理并复测

把错误分成连接失败、鉴权失败、字段错误、超时四类后，接入才稳定可维护。可以用下面的分支骨架，在捕获异常或拿到状态码后先分类，再选择动作和复测方式。

try:
    resp = session.post(url, json=payload, timeout=(5, 120))
except ConnectionError:
    # 连接失败：检查地址、端口、DNS、网络策略
    ...
except Timeout:
    # 超时：记录耗时，再决定调大读取超时或减少输出
    ...
else:
    if resp.status_code in (401, 403):
        # 鉴权失败：检查密钥、请求头字段名、是否有多余空格
        ...
    elif 400 <= resp.status_code < 500:
        # 字段错误：打印错误信息，对照请求体检查字段名和类型
        ...
    else:
        # 成功：先打印原始响应体确认层级，再解析
        ...

四类复测方式不同。连接失败改地址或网络策略后，先用 curl 打一次最小请求确认连通，再走完整调用；鉴权失败改密钥或请求头后，用同一份请求体复测，观察状态码是否变化；字段错误改一个字段就复测一次，避免同时改多个；超时先记录一次长输出的真实耗时，再按新超时值跑同一提示词，确认返回体完整。四类都通过后，再去调输出效果相关参数，才有可比较的基线。