baseURL、endpoint 与 model ID

建议用时：25 分钟（含练习）

学习目标

能够从完整请求地址中分出 baseURL 和 endpoint，并核对工具需要的模型名。

本节产出

一张 API 地址拆解卡

核心知识：地址正确，才谈得上模型选择

接入模型工具时，经常看到三个配置项：baseURL、endpoint 和 model ID。它们负责不同的定位工作。baseURL 通常是客户端使用的服务基础地址；endpoint 表示具体接口路径，有时也被文档用来指完整请求地址。因为术语用法存在差异，最终应检查程序实际发出的完整 URL，而不能只凭字段名称推断。

以虚构配置为例，工具要求 baseURL 为 https://api.example.invalid/v1，SDK 再追加 /chat/completions，最终路径是 /v1/chat/completions。另一个工具可能要求你填写完整地址。如果把完整接口地址填进前一种工具，它可能重复追加路径；如果 SDK 本来会追加 /v1，你又写一次，就可能得到 /v1/v1/...。

模型名不会修复地址错误。 服务地址决定请求去了哪里，接口路径决定调用哪项能力，模型标识在请求被正确解析后才用于选择模型。有些服务也会把模型或部署名称放在 URL 中，但仍然要按该服务的合同处理，不能从另一家服务照搬配置。

图示采用在请求体中指定 model ID 的情景，无箭头连线说明请求的组成关系，不代表所有服务都采用同样格式。其中“拼接规则”是最容易被忽略的一步。尾部斜杠、路径前缀和 SDK 的默认规则都会影响结果。程序也可能采用 URL 解析而非简单字符串相加，因此应查工具说明或脱敏调试输出，不要发明一个适用于所有 SDK 的斜杠口诀。

model ID 是服务合同的一部分

术语

model ID

model ID 是服务识别某个模型或路由目标的标识。网页展示名称、模型家族名称和 API 标识可能不同。一家网关还可能使用别名，把请求转到另一个实际模型。即使两个服务都接受同一个字符串，也不能仅凭名称断定它们的上下文窗口、工具调用、图像输入或返回字段完全相同。

正确配置需要知道模型标识从哪里获得：官方文档、当前账号可见的模型列表，或你有权管理的网关路由配置。模型列表接口并非所有服务都提供；列表中出现某模型，也不自动证明账号具备所有接口形态的调用权限。涉及权限与能力时，需要进一步核对。

案例：三个看起来相似的 404

以下均为虚构排错情景。情景甲使用 /v1/v1/chat/completions，响应是网关通用 HTML 错误页；情景乙访问 /v1/chat/completions，返回 JSON，提示目标模型不存在；情景丙使用正确路径和模型标识，但请求被转到另一个没有该路由的域名。

这三种情况都可能表现为 404，却处于不同层次。甲先检查地址拼接，乙检查模型列表或权限映射，丙检查实际请求主机和重定向行为。只反复更换 API Key 既不能定位问题，也可能把凭证发送给错误服务。

排错记录应写下脱敏后的主机、路径、方法、状态码、内容类型和错误类别。不需要打印 Authorization 头。若请求发生重定向，也要确认最终目标是否符合预期；不要随意开启跨域携带认证信息的选项来“让它能用”。

配置说明要写给下一位维护者

不要只保存三个字符串。旁边应说明“这个工具会自动追加哪段路径”“模型标识核对日期”“密钥从受保护配置读取”等信息。例子必须明显使用占位符，避免读者把教学字符串当作当前可用模型名。长期文档更适合解释配置关系，具体型号与价格则链接到维护中的官方页面。

动手练习

1. 假设工具合同规定 baseURL 为 https://api.example.invalid/v1，追加路径为 /responses。写出最终 URL，并标出哪一部分由工具追加。
2. 检查这项错误配置：baseURL 填成 https://api.example.invalid/v1/responses，工具仍追加 /responses。说明错误在哪里，而不是尝试修改模型名。
3. 为一款你已获准使用的工具制作脱敏配置卡。若无法检查实际请求，只记录文档规定与尚待验证项。

参考答案与推演

展开

完成检查

• 能解释基础地址、完整 endpoint 和 model ID 的不同作用。
• 能定位重复前缀或重复接口路径，不靠盲目试值。
• 配置卡写清拼接规则和模型标识来源。
• 不把通用 404 直接解释成某一种固定原因。

参考与来源

• OpenAI 官方 Python SDK：查看客户端配置、基础地址与请求示例。
• MDN：URL：了解 URL 解析与组成部分。