LingBot-Video 在多模态模型服务中的接口兼容排查

LingBot-Video 作为视频生成服务接入统一推理网关时，最常见的失败并不是模型推理本身，而是网关转发、请求体字段和响应 JSON 结构这三层错位。如果客户端报错或返回格式与预期不符，建议按访问链路逐层排查，先确认请求是否到达服务，再核对字段、鉴权和响应结构，最后记录一次完整错误链。

适用场景：LingBot-Video 已部署为 HTTP 服务，客户端经网关调用报错或拿不到视频。处理方向：从访问日志、请求体字段、鉴权路由、响应字段名四个层面依序排查。验证方式：用 curl 绕过网关直连服务，用 python 脚本比对字段类型，再对比客户端解析逻辑。风险边界：不同版本服务端字段命名可能变化，需结合当前环境确认。

先从访问日志确认请求是否到达服务

先区分问题发生在网关路由还是服务内部。在服务所在主机执行 curl，直接请求 LingBot-Video 的健康检查或生成接口，看能否返回非 5xx 响应。

curl -v http://127.0.0.1:8000/health
curl -v -X POST http://127.0.0.1:8000/generate \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"test"}'

如果直连正常，再看 nginx 或网关容器日志中该 URL 的访问记录。nginx 默认访问日志包含请求方法、路径、状态码和响应时间，可以用 tail 实时观察。

tail -f /var/log/nginx/access.log

状态码初步判断：404 通常是网关或服务中路径前缀没转发对，说明路由规则未匹配；403 通常是 nginx 层有 IP 或 referer 限制；500 则是服务内部异常，需要翻服务日志。这里要特别注意，nginx 日志里出现 404 但服务日志没有记录，说明请求根本没到 LingBot-Video 进程，问题出在 nginx 的 location 或 upstream 配置。

比对请求体中的必填字段与模型入口要求

请求到达服务后，若返回 400 或模型侧参数校验错误，常见原因是请求体缺字段或字段类型不一致。LingBot-Video 的模型入口可能使用 Pydantic 或类似校验，字段缺失会给出具体错误信息。先用 python 读入请求体，检查预期字段是否存在及类型。

import json, sys

with open('request.json') as f:
    req = json.load(f)

required_fields = {
    'prompt': str,
    'duration': int,
    'resolution': str,
    'negative_prompt': str,
}

for field, typ in required_fields.items():
    if field not in req:
        print(f'MISSING: {field}')
    elif not isinstance(req[field], typ):
        print(f'TYPE ERROR: {field} expected {typ.__name__}, got {type(req[field]).__name__}')
    else:
        print(f'OK: {field}')

将客户端发送的 JSON body 保存为 request.json，运行这段脚本。如果服务端返回的错误信息提示缺少 content 之类字段，而脚本没有报错，说明服务端要求字段名与客户端发送的不一致，需要核对模型入口的实际字段列表，而不是盲目补字段。

检查鉴权信息和路由前缀是否匹配

401/403 类错误在网关场景中通常是鉴权头或前缀转发不一致。先在网关配置文件里确认 API key/token 的传递位置，常见是在请求头 Authorization 或 X-API-Key，且网关可能在转发前剥掉该头。LingBot-Video 如果要求某种鉴权，客户端请求头里必须有对应内容，同时网关不能把它替换成无效值。

路由前缀方面，假设服务挂载在 /video，网关将 /api/video 转发到服务 /video，若 nginx 配置的 proxy_pass 没有带 trailing slash，路径拼接会出现问题。检查 nginx 配置中 location 和 proxy_pass 的组合，例如：

location /api/video {
    proxy_pass http://lingbot-backend:8000/video/;
}

这种写法会把 /api/video/xxx 转发为 /video/xxx；若去掉 proxy_pass 末尾的斜杠，则可能变成 /video/xxx 或不带前缀，取决于完整路径。结合服务端访问日志确认实际收到的 URL 路径，修正网关转发规则。

验证响应JSON中的视频字段名是否被客户端正确解析

返回 HTTP 200 但客户端拿不到视频来源，通常是响应 JSON 里字段名和客户端解析的不一致。在命令行直接执行一段 python，打印响应 JSON 的所有顶层 keys，并定位视频 URL 字段。

import requests, json

resp = requests.post('http://127.0.0.1:8000/generate',
                     json={'prompt': 'a cat walking'},
                     timeout=30)
data = resp.json()
print(data.keys())

# 若 keys 中包含 video_url 或 url，则打印出来
for key in ('video_url', 'url', 'download_url', 'video'):
    if key in data:
        print(key, '=', data[key])

客户端应避免写死字段名。若服务端返回的是嵌套结构，例如 data.video.url，客户端需要逐层取。有些实现会在响应中同时返回 video_id 和 status，客户端需先判断 status 是否为成功，再取出最终视频地址，而不是一拿到响应就去读 url 字段。这里最好和当前服务端实际返回的 JSON Schema 对照，确认字段路径。

复现并记录一次完整错误链

排查到具体异常后，要形成可复现的记录。记录从客户端请求到服务端日志的完整时间线，方便提交给上游修复。下面是一个时间线模板：

时间            | 层       | 内容
14:00:00.123   | 客户端   | POST /api/video/generate body={"prompt":"x"}
14:00:00.220   | 网关     | 转发到 10.0.0.5:8000/video/generate，Header: X-API-Key: ***
14:00:00.310   | 服务     | 收到请求，返回 400 {"detail":"prompt field required"}
14:00:00.315   | 网关     | 返回 400 给客户端
14:00:00.316   | 客户端   | 报错：InvalidResponseError

通知上游修复时，提供最小示例：一段 curl 或 python 请求代码、请求 JSON、网关转发配置片段、服务端返回的错误响应。不需要贴完整日志，但要把关键路径和字段差异标出来。若服务端要求某个字段类型为 float 而客户端传了 int，错误链记录里应明确写出该差异，避免修复时只改客户端而忽略服务端校验。