OpenAI Python SDK模型目录预检：用MockTransport检查精确ID与错误分支

最新推荐文章于 2026-11-12 20:15:00 发布

原创最新推荐文章于 2026-11-12 20:15:00 发布 · 106 阅读

本内容遵循CC 4.0 BY-SA版权协议

本文介绍基于OpenAI Python SDK的离线模型ID预检方案，使用MockTransport模拟/models接口响应，验证精确模型ID匹配、目录结构、HTTP错误码（401/403/404/429/500）、分页拒绝、大小写敏感性及非JSON容错。工具不发起真实API调用，输出明确标识generation_tested=false，聚焦配置层可信验证。

作者说明：本文由FlowBarCN团队提供，涉及自家服务，由AI辅助整理并经本地代码检查。示例ID均为虚构，本轮没有真实模型调用。

把模型ID写进环境配置后，是否需要马上发一条生成请求来“试一下”？对配置检查来说，先做离线验证更容易定位问题，也不会把拼写错误和权限问题混到生成结果里。

今天做一个可直接运行的小工具：用OpenAI Python SDK读取模拟的/models响应，检查精确ID、目标地址、目录形状、重复项和HTTP错误；结果明确写出generation_tested=false。它没有查询任何真实账户，也没有调用chat/completions。

1. 先定义预检能证明的范围

OpenAI官方models/list接口用于列出模型基本信息，ID是可引用的标识；它不是参数能力清单。兼容服务是否返回相同结构，要核对它自己的文档。官方接口说明

FlowBarCN公开文档给出https://flowbar.cn/v1作为兼容地址，以及模型目录入口；公开模型页注明是精选展示。本文不猜测当前账户目录内容，演示只访问MockTransport接管的https://mock.invalid/v1/models。FlowBarCN文档 · 公开模型页

近期Anthropic在2026年10月22日更新了其Google Cloud访问路径，说明模型品牌相同也需要核对具体访问体系；本篇不演示该产品，亦不宣称本站支持。官方日志

2. 环境和输入输出约定

本轮实际环境：Python 3.11.9、openai 3.35.1、httpx 0.28.1。以下安装命令供读者在独立环境复现；示例运行不要求真实密钥：

python -m venv .venv
.venv\Scripts\python.exe -m pip install openai==3.35.1 httpx==0.28.1

macOS/Linux把解释器路径换为.venv/bin/python。

输入包括：端点、精确模型ID、端点允许集合、显式传入的transport。输出只说明目录包含精确ID，并保留生成未验证标志。

这里的ID正则是项目自己的限制，不是声称厂商所有模型ID都只能如此命名。需要接受其他字符时，先核对目标文档再调整策略，不要一边报错一边静默删字符。

3. 完整代码：model_preflight.py

"""SDK catalog preflight with an injected transport. Demo performs no network IO."""
import json
import re
from urllib.parse import urlsplit

import httpx
from openai import APIConnectionError, APIStatusError, OpenAI


class PreflightError(ValueError):
    pass


def checked_id(value):
    # This is OUR project's grammar, not a provider-wide specification.
    if type(value) is not str or not re.fullmatch(
        r"[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}", value
    ):
        raise PreflightError("invalid_model_id")
    return value


def checked_endpoint(value, allowed):
    if type(value) is not str or value not in allowed:
        raise PreflightError("unapproved_endpoint")
    parts = urlsplit(value)
    if (parts.scheme != "https" or not parts.hostname or parts.username
            or parts.password or parts.query or parts.fragment):
        raise PreflightError("invalid_endpoint")
    return value


def parse_catalog(raw):
    if type(raw) is not dict or raw.get("object") != "list":
        raise PreflightError("invalid_catalog")
    rows = raw.get("data")
    if type(rows) is not list or not 1 <= len(rows) <= 1000:
        raise PreflightError("invalid_catalog_size")
    # This small example supports one complete page only.
    if raw.get("has_more", False) is not False:
        raise PreflightError("pagination_not_supported")
    ids = set()
    for row in rows:
        if type(row) is not dict or row.get("object") != "model":
            raise PreflightError("invalid_catalog_row")
        model_id = checked_id(row.get("id"))
        if model_id in ids:
            raise PreflightError("duplicate_model_id")
        ids.add(model_id)
    return ids


def preflight(*, endpoint, model_id, allowed, transport):
    endpoint = checked_endpoint(endpoint, allowed)
    model_id = checked_id(model_id)
    # No real key is read, even from the environment. A real catalog query
    # would require separately configured credentials and authorization.
    with httpx.Client(transport=transport, trust_env=False,
                      follow_redirects=False, timeout=5.0) as http:
        with OpenAI(base_url=endpoint, api_key="offline-placeholder",
                    http_client=http, max_retries=0) as client:
            try:
                response = client.models.with_raw_response.list()
                try:
                    raw = response.http_response.json()
                finally:
                    response.http_response.close()
                ids = parse_catalog(raw)
            except APIStatusError as exc:
                raise PreflightError(f"catalog_http_{exc.status_code}") from None
            except APIConnectionError:
                raise PreflightError("catalog_transport_failed") from None
            except (json.JSONDecodeError, UnicodeError):
                raise PreflightError("catalog_invalid_json") from None
    if model_id not in ids:
        raise PreflightError("model_not_listed")
    return {"catalog_contains_exact_id": True,
            "generation_tested": False, "endpoint": endpoint,
            "model_id": model_id}


def demo_transport():
    def handle(request):
        if request.method != "GET" or str(request.url) != "https://mock.invalid/v1/models":
            raise AssertionError("unexpected_request")
        return httpx.Response(200, json={"object": "list", "data": [
            {"object": "model", "id": "demo-text-2026-10",
             "created": 0, "owned_by": "demo"}
        ]})
    return httpx.MockTransport(handle)


if __name__ == "__main__":
    result = preflight(endpoint="https://mock.invalid/v1",
                       model_id="demo-text-2026-10",
                       allowed={"https://mock.invalid/v1"},
                       transport=demo_transport())
    print(json.dumps(result, ensure_ascii=False, indent=2))

运行：

.venv\Scripts\python.exe model_preflight.py

本轮实际输出：

{
  "catalog_contains_exact_id": true,
  "generation_tested": false,
  "endpoint": "https://mock.invalid/v1",
  "model_id": "demo-text-2026-10"
}

model_preflight.py是完整离线入口。不要只改endpoint就当作线上脚本使用：示例中的密钥是固定占位，模拟处理器也仅接受固定地址。线上目录查询需要另行配置凭据、访问授权和错误策略，本文不提供自动切换到真实请求的开关。

4. 这几处实现关系到结果可信度

先检查目标，再构造请求。 允许集合做精确匹配，再检查HTTPS、用户名密码、查询串和片段。它阻止错误配置离开应用边界，不是完整的SSRF防护或DNS安全方案。

读取原始JSON，再做项目校验。 示例使用with_raw_response.list()，自行检查根对象、data、条目类型和精确ID。并不依赖SDK类型标注替应用验证所有业务条件。非流式raw response不是上下文管理器，因此使用try/finally关闭底层响应。

明确拒绝未实现的分页。 has_more为true时直接报pagination_not_supported。实际接入带分页的服务时应按其契约循环并限制页数、总条数；不要仅检查第一页就声称某模型不存在。

不自动兜底到其他模型。 没找到ID返回model_not_listed，大小写不同也不强行修正。迁移到另一个模型应作为独立变更处理。

错误只保留稳定码。 HTTP失败输出catalog_http_401等代码，不回显上游原始错误正文和认证头。max_retries=0使本例每次HTTP错误只有一次目录请求，避免把重复请求混进验证。

5. 快速复现三个失败样本

保留主文件，在同目录另存bad_cases.py：

import httpx
from model_preflight import PreflightError, preflight

for status in (401, 404, 429):
    transport = httpx.MockTransport(
        lambda request, code=status: httpx.Response(
            code, json={"error": {"message": "demo error"}}
        )
    )
    try:
        preflight(endpoint="https://mock.invalid/v1",
                  model_id="demo-text-2026-10",
                  allowed={"https://mock.invalid/v1"},
                  transport=transport)
    except PreflightError as exc:
        print(exc)

运行python bad_cases.py，本轮实际输出：

catalog_http_401
catalog_http_404
catalog_http_429

这些是我们构造的错误，不是FlowBarCN线上故障。不同服务的404可能涉及路径或模型，401/403涉及认证和权限，429也不应一律当成余额问题；真实诊断应遵循服务方文档，并保存脱敏请求编号。

6. 常见报错与定位顺序

错误	本例含义	优先检查
invalid_model_id	ID不满足本项目规则	空格、类型、长度、约定字符
unapproved_endpoint	目标未在允许集合	是否误抄文档页地址或另一套环境
model_not_listed	当前响应没有精确ID	ID大小写、目录范围和采集时刻
invalid_catalog / invalid_catalog_row	返回形状不符合本例契约	是否拿到HTML、包装层或另一API
duplicate_model_id	同一响应重复列出ID	别急着去重，先核对源数据
pagination_not_supported	目录尚有后续页	实现分页后再作完整性判断

目录通过之后，能力、权限、额度和实际生成仍需分别验证；还要看响应采集时间。把今天保存的目录带到下个月运行，只能证明旧样本的内容，不能证明下个月的实时状态。

7. 实际检查与今日小练习

本轮执行了12个测试方法，其中目录预检9个、独立业务映射策略3个。覆盖了HTTP 401/403/404/429/500、精确大小写、空格、错误目标不触发transport、格式错误、重复项、分页、条数限制及非JSON响应。所有网络行为均由MockTransport接管；没有真实模型请求和性能测试。

练习：把模拟目录里的ID改成demo-text-2026-11，保持待检查ID不变，观察model_not_listed；再同步修改待检查ID，确认输出依然是generation_tested=false。最后加has_more=true，检查工具是否诚实拒绝不完整目录。

下篇实现参数允许列表：模型ID正确后，如何在请求发出前隔离未经确认的参数。

你可以先收藏完整代码和排错表。如果接入FlowBarCN，请从官方公开文档核对目标信息；留言时仅描述脱敏错误码和配置形状，不粘贴API Key、认证头或用户原文。

标签

#python