入门知识

这篇文章面向第一次调用大模型的开发者，也适合在 Codex、Cursor、Continue 等工具中配置模型的用户。你不需要先掌握机器学习，先理解“请求发到哪里、请求长什么样、平台如何把请求转给模型”就可以开始排查大多数问题。

先记住一条调用链

一次模型调用通常经过下面几层：

你的应用或开发工具
        ↓  HTTP + JSON + API Key
API Base URL（华明平台）
        ↓  鉴权、限流、路由、协议转换
上游模型渠道
        ↓
模型服务商和具体模型

华明平台的公开接口使用 OpenAI 兼容格式。一般只需要在 SDK 或工具中设置三项：

配置项	示例	作用
Base URL	`https://www.walmind.cn/v1`	指向 API 服务，不要重复拼接 `/v1`
API Key	`sk-your-api-key`	用于鉴权和用量归属
Model	`your-model-id`	使用 `/models` 返回的模型 ID

快速验证服务和 Key 是否可用：

export API_BASE_URL="https://www.walmind.cn/v1"
export API_KEY="sk-your-api-key"

curl "$API_BASE_URL/models" \
  -H "Authorization: Bearer $API_KEY"

如果这里已经失败，先不要修改 messages 或模型参数，优先检查地址、Key 和网络。

什么是“协议”

这里的协议不是模型本身，而是客户端与服务端约定的通信方式，主要包括：

地址：例如 /v1/models、/v1/chat/completions。
鉴权：通常在 Authorization: Bearer ... 请求头中发送 Key。
请求 JSON：例如 model、messages、temperature、stream。
响应 JSON 或 SSE：非流式返回完整 JSON，流式返回一段段 data: ...。
错误格式：HTTP 状态码、错误消息和可选的错误类型或 code。

因此，“支持某个模型”与“客户端能否直接调用”是两件事：模型可能已经接入平台，但客户端使用了不匹配的协议或参数，仍然会调用失败。

原生协议和 OpenAI 兼容协议

原生厂商协议

模型厂商可以设计自己的 API 路径、字段和 SDK。例如，有些国内平台常见的入口名称是 chat，消息字段和参数也可能与其他平台不同；有的服务使用厂商自己的响应字段、工具调用格式或鉴权方式。使用原生协议时，要按照该厂商的文档配置完整的 endpoint、请求体和响应解析。

OpenAI 兼容协议

OpenAI Chat Completions 逐渐成为许多开发工具默认支持的形状，典型请求如下：

POST /v1/chat/completions
Authorization: Bearer sk-your-api-key
Content-Type: application/json

{
  "model": "your-model-id",
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "stream": false
}

OpenAI 兼容的意思是“请求和响应的主要结构相近”，不代表所有模型都支持完全相同的参数。tools、视觉输入、推理参数、上下文长度和流式细节仍要以模型和渠道能力为准。

国产模型和海外模型应该怎么理解

“国产一般是 chat，海外都是 OpenAI 格式”只能作为非常粗略的经验，不能当作接口规则：

情况	你可能看到的接口	处理方式
国内厂商原生 API	`chat`、厂商专用路径或专用 SDK	按该厂商文档调用，不能只替换 Base URL
国内厂商提供兼容层	`/v1/chat/completions` 等	按 OpenAI 兼容客户端配置，确认兼容范围
海外厂商原生 API	厂商自己的 messages、responses 或其他接口	使用厂商 SDK 或适配器
华明平台统一入口	`/v1/models`、`/v1/chat/completions`	使用本页所述 OpenAI 兼容配置

很多海外模型服务也有自己的原生协议；同时，很多国内模型也提供 OpenAI 兼容接口。真正需要确认的是：当前客户端发送的协议，是否与当前 Base URL 暴露的协议一致。

在 Codex 等工具中调用国产模型

优先选择华明平台提供的 OpenAI 兼容分组或兼容入口，配置为：

Base URL: https://www.walmind.cn/v1
API Key: 你的华明 API Key
Model: /models 返回的模型 ID
协议: OpenAI Compatible / OpenAI 格式

华明平台会在统一入口完成鉴权、路由，以及在需要时将 OpenAI 风格请求转换为上游渠道的原生协议。这样，Codex 或其他只会发送 OpenAI 格式请求的客户端，不必直接理解每家国产模型的原生 chat 协议。

如果某个模型在华明平台上没有配置协议转换，或者你必须直连某个原生渠道，客户端就需要发送该渠道要求的请求格式。此时可以在本地使用 cc-switch 一类的协议转换工具，把客户端的 OpenAI 风格请求转换成目标渠道的格式。请从项目官方渠道获取软件，并按其文档配置；转换工具是额外的一层代理，遇到问题时要分别检查客户端、转换工具和上游渠道三段日志。

推荐排查顺序

先用 curl /models 确认华明接口和 Key 正常，再用最小化的 chat/completions 请求验证模型，最后才把请求接入 Codex、IDE 插件或自己的业务代码。

一次对话请求需要哪些字段

最小请求只需要 model 和 messages：

{
  "model": "your-model-id",
  "messages": [
    {"role": "user", "content": "请用一句话介绍 API。"}
  ]
}

常见字段的含义：

字段	说明	注意事项
`model`	模型 ID	必须使用 `/models` 返回的值
`messages`	按顺序排列的对话消息	常见角色为 `system`、`user`、`assistant`
`stream`	是否以 SSE 流式返回	调试时可先设为 `false`
`temperature`	输出随机性	不同模型支持范围可能不同
`max_tokens`	限制本次生成长度	过大可能超过余额或上下文限制
`tools`	工具调用定义	只有支持工具调用的模型和渠道可用

建议先用最小请求得到成功响应，再逐项加入系统提示词、历史消息、图片、工具和高级参数。这样能快速定位到底是协议问题、模型能力问题，还是业务参数问题。

流式响应要知道什么

stream: false 会等待模型完成后返回一个 JSON；stream: true 通常返回 text/event-stream，客户端需要持续读取多个 data: 数据块，并在收到 data: [DONE] 后结束。

流式请求常见的误区：

代理或网关没有正确转发 SSE，导致客户端一直等待或一次性收到全部内容。
代码只读取一次 HTTP body，丢失后续数据块。
把流式响应当作完整 JSON 解析，遇到第一段就报 JSON 错误。
浏览器前端直接暴露 API Key。生产环境应由服务端代发请求。

排查连接问题时，先使用 stream: false；确认非流式请求成功后，再打开流式响应。

华明平台常见错误

下面的错误名称和消息会因版本、渠道和网关而略有不同。先看 HTTP 状态码和完整响应体，再结合服务端请求 ID 排查。

现象或错误关键词	常见原因	建议处理
`401`、`invalid_api_key`、`无效的令牌`	Key 缺失、复制错误、已禁用，或 `Bearer` 格式不对	检查请求头是否为 `Authorization: Bearer <Key>`，重新从平台复制 Key
`403`、`无权限`	Key 所属用户或分组没有该模型权限	确认分组、模型授权和账户状态，联系平台管理员
`404`、`model not found`	模型 ID 写错，或路径中重复/漏写 `/v1`	先请求 `/models`，复制返回的 `id`；检查 Base URL 与接口路径拼接
`无可用渠道`、`no available channel`	平台没有可用上游渠道，渠道被禁用、余额不足或模型映射不一致	让管理员检查渠道状态、模型映射、余额和分组路由
`model mapping`、上游模型不存在	平台模型名与上游渠道模型名不同，映射未配置	使用平台公开的模型 ID，并由管理员补充渠道映射
`400`、`invalid_request_error`	JSON 格式错误、必填字段缺失或参数类型错误	用最小请求重试，检查 `model`、`messages`、JSON 引号和参数类型
`不支持该参数`、`unsupported parameter`	当前模型或上游渠道不支持 `tools`、`temperature`、视觉字段等	删除可选参数逐项重试，按模型能力调整请求
`上下文长度超限`、`maximum context length`	历史消息和本次输出超过模型上下文窗口	压缩历史消息、减少输入，或选择上下文更大的模型
`429`、`rate limit`、`额度不足`	触发频率限制、并发限制或账户额度限制	降低并发并使用指数退避；额度问题需充值或联系管理员
`500`、`502`、`503`、`timeout`	平台网关或上游渠道暂时异常	保存请求时间和 request ID，稍后重试；持续失败时联系管理员
`content policy`、内容安全拦截	上游模型或渠道拒绝了请求内容	调整输入内容，确认目标模型的安全策略
能返回但内容为空或流式中断	上游响应格式、SSE 转发或客户端读取逻辑不兼容	先关闭 `stream` 验证；保留完整响应和日志进行定位

记录哪些信息最有用

向管理员反馈问题时，提供以下信息比只说“调用失败”更容易定位：

请求时间（含时区）。
请求的 HTTP 状态码和完整错误体。
Base URL（可以隐藏域名路径中不便公开的部分）和模型 ID。
是否使用 Codex、SDK、cc-switch 或其他代理，以及它们的版本。
是否只有某个模型失败，还是 /models 和所有模型都失败。
request ID 或网关日志中的追踪 ID。

请不要提交 API Key、完整的隐私数据或包含密钥的请求头。

开发者的最小检查清单

Base URL 只有一个 /v1，接口路径与客户端配置没有重复拼接。
API Key 放在环境变量或密钥管理系统中，没有提交到 Git 或前端代码。
用 /models 检查模型 ID，而不是凭记忆填写上游名称。
先用非流式、最小 JSON 请求验证链路。
确认客户端使用 OpenAI 兼容格式，或已经配置了协议转换层。
出现 429、502、503 时做有限次数的指数退避；400、401、403 不要原样无限重试。
遇到上游渠道错误时，记录时间、状态码、错误体和 request ID。

接下来可以阅读快速开始完成第一次调用，或查看接口格式与分类选择 Chat Completions、Responses、Claude、Gemini 或其他模型接口格式。

先记住一条调用链​

什么是“协议”​

原生协议和 OpenAI 兼容协议​

原生厂商协议​

OpenAI 兼容协议​

国产模型和海外模型应该怎么理解​

在 Codex 等工具中调用国产模型​

一次对话请求需要哪些字段​

流式响应要知道什么​

华明平台常见错误​

记录哪些信息最有用​

开发者的最小检查清单​