JellyToken 接入 OpenAI 兼容接口的配置方法

JellyToken 接入 OpenAI 兼容接口，核心是改三个值：base_url、api_key、model。只要现有代码走的是 OpenAI 官方 SDK 或标准 HTTP 调用，通常不需要改业务逻辑；真正容易出问题的是模型名不识别和鉴权头格式。下面按控制台取信息、改代码、验模型名、查日志四步处理，每一步都能独立验证。

判断：JellyToken 兼容层是否可用，取决于控制台是否给出「接口基地址 + 密钥 + 模型标识」三项。操作动作是把 OpenAI SDK 的 base_url 指向 JellyToken 接口入口，api_key 换成 JellyToken 生成值，model 换成控制台模型列表里的实际名称。验证方式是先列模型再发请求，看返回状态码。风险点是路径拼接和密钥前缀，建议先用 curl 确认接口可达，再改代码。

先确认 JellyToken 控制台的接口接入信息

先不要改代码。登录 JellyToken 控制台后，重点找两个页面：API 密钥管理页和模型列表页。密钥管理页负责创建和查看 api_key，通常有“创建密钥”“API Keys”这类入口；模型列表页会列出当前账号可用的模型标识，有的控制台叫“模型市场”或“模型管理”。

需要从控制台记录三项内容：

接口基地址（base_url）：一般是控制台里标明的 API 入口地址，用于拼接请求路径。注意看清尾缀是否带 /v1，带不带会直接影响 OpenAI SDK 的拼接结果。
密钥（api_key）：在密钥管理页生成，生成后立即复制并保存。许多平台只在创建时显示完整密钥，离开页面后就只能看到前缀或掩码。
可用模型名称（model）：从模型列表页复制完整的模型标识，不要凭印象填“gpt-3.5-turbo”这类 OpenAI 原名。兼容层通常要求模型名与控制台返回的 id 完全一致。

如果控制台同时提供了“接口文档”或“快速接入”入口，可以打开对照确认：接口基地址、鉴权方式、路径示例。这个页面里的信息比外部教程更可靠，因为不同租户或不同部署环境的地址可能不同。

在现有代码中替换 OpenAI base_url 与密钥

拿到控制台信息后，最小改动是修改 OpenAI SDK 客户端的初始化参数。以 Python 的 openai 库为例，兼容接口通常可以通过设置 base_url 和 api_key 来切换目标服务：

from openai import OpenAI

client = OpenAI(
    base_url="https://你的控制台显示的接口地址",  # 例: https://api.example.com/v1
    api_key="jlt_你的JellyToken密钥",            # 以控制台实际前缀和完整值为准
    timeout=30.0,                                   # 建议设置显式超时，避免卡死
)

response = client.chat.completions.create(
    model="控制台里的实际模型名",
    messages=[
        {"role": "user", "content": "你好"}
    ],
)
print(response.choices[0].message.content)

需要注意：base_url 必须以控制台显示的完整基地址为准，不要自己拼路径。如果控制台给的是 https://api.xxx.com 且未带 /v1，而 OpenAI SDK 会自动追加 /chat/completions，那么实际请求路径可能是 https://api.xxx.com/chat/completions；如果控制台文档要求走 /v1/chat/completions，就要在 base_url 末尾补上 /v1。密钥同理，需要确认控制台生成的密钥是否带前缀（例如 jlt_），带前缀就完整复制。

超时设置建议显式传入，默认值可能过长或过短；先给 30 秒，等确认接口稳定后再调整。如果现有代码里已经用环境变量读取 OPENAI_API_KEY 和 OPENAI_BASE_URL，也可以直接修改这两个环境变量，代码本身不用动。

验证模型名映射是否生效

最常见的报错是 model not found 或 The model xxx does not exist。这是因为请求里的 model 填了 OpenAI 原模型名，而 JellyToken 兼容层只认自己管理的模型标识。验证方法可以先列出模型列表，再检查实际返回的 id 字段。

以下代码使用 OpenAI SDK 的 models.list 方法，把可用模型 id 打印出来：

from openai import OpenAI

client = OpenAI(
    base_url="你的接口基地址/v1",
    api_key="你的JellyToken密钥",
)

models = client.models.list()
for m in models.data:
    print(m.id)
# 示例输出可能是:
# jlt-7b-chat
# jlt-13b-chat
# embedding-v1

拿到模型 id 后，把请求里的 model 字段替换为列表中的完整名称。替换后再次调用，如果返回 200 或成功拿到响应内容，说明模型名映射生效。若列表为空或接口返回 404/403，则问题不在模型名，需要回到第一步核对 base_url 和鉴权配置。

另一种验证方式是直接用 curl 请求一次模型列表接口，这样能避开 SDK 的封装，更容易判断是客户端问题还是服务端问题：

curl -s https://你的接口基地址/v1/models \
  -H "Authorization: Bearer 你的JellyToken密钥"

返回 JSON 中 data 数组里的 id 就是可用的模型名。如果 curl 能列出来但 SDK 不行，先检查 SDK 版本和 base_url 是否一致。

排查鉴权失败和 404 的常见原因

当调用返回 401 Unauthorized、403 Forbidden 或 404 Not Found 时，按日志逐层检查，不要急着改代码。最常见的原因是鉴权头格式、路径拼接和密钥前缀这三类。

先用 curl 直接请求接口入口，观察返回信息：

curl -i https://你的接口基地址/v1/models \
  -H "Authorization: Bearer 你的JellyToken密钥"

-i 会让 curl 输出响应头，方便看状态码和错误信息。逐项检查：

Authorization 头格式：OpenAI 兼容接口通常要求 Authorization: Bearer <api_key>。注意“Bearer”和密钥之间有一个空格，密钥不要用引号包裹。如果控制台文档写的是 api-key 或 X-API-Key 方式，那就要按控制台文档调整，不能用 OpenAI 的默认写法。
密钥是否完整：有些平台会生成带前缀的密钥，比如 jlt_ 开头。复制时漏掉前缀或混入空格都会导致鉴权失败。检查请求头里打印出来的密钥是否与控制台生成的一致。
base_url 与路径拼接：OpenAI SDK 会把 base_url 和具体的资源路径拼接。base_url 结尾是 /v1，实际请求就是 /v1/models；结尾没有 /v1，请求就变成 /models。如果控制台文档明确要求 /v1/models，但你的代码请求落在 /models 上，就会得到 404。建议在日志里打印实际请求的完整 URL，或者用 curl 与 SDK 请求同一个路径，对比结果。

另一个容易忽略的点是代理或网关层。如果本地代码经过 HTTP 代理访问 JellyToken 接口，代理 URL 解析失败会表现为 404 或连接异常。可以先在环境变量里临时取消代理测试一次，排除网络层干扰。若仍不确定，就分别用 curl 和代码请求同一个相对路径，比较返回体中的错误提示；错误提示通常会写明是认证失败、模型不存在还是路径不存在。

最后建议：接入完成后，保留一条最简请求（比如 models.list()）作为巡检脚本。后续如果某个业务报错，先跑该脚本判断是 JellyToken 接口变更还是业务代码改动，能明显减少排查时间。