书生·浦语本地模型接入 OpenAI 兼容接口的配置方法

书生·浦语本地模型要接入现有 OpenAI 客户端，核心思路不是改写业务代码，而是在模型和客户端之间加一层 OpenAI 兼容服务。这个服务把本地模型的 HTTP 路由、请求体和鉴权格式转换成 OpenAI 接口的样子，客户端只需要改 base_url 和 model，其余保持原样。配置前先确认两件事：本地模型是否已经能用原始推理脚本启动，以及计划使用的端口是否被占用。

适用场景：已有代码基于 OpenAI SDK 或 OpenAI 协议调用，希望把本地书生·浦语模型接入而不重写客户端。操作动作：启动一个 OpenAI 兼容服务层，指定模型路径和端口，设置虚拟密钥，然后把客户端 base_url 指向该端口。验证方式：先用 curl 带 Authorization 请求一次对话补全接口，确认返回 JSON 后再改 SDK。风险边界：兼容层只负责协议转换，模型行为、显存占用和推理稳定性仍取决于本地部署环境，需要结合环境确认。

选择适合的 OpenAI 兼容服务层

目前常见的做法是使用通用 OpenAI 兼容代理程序，这类程序本身不携带模型，而是通过启动参数指向本地已经加载好的模型服务。选择时要看三点：能否指定模型路径、能否指定监听端口、是否支持 chat.completions 和 completions 两种路由。不同程序的参数名略有差异，但核心必填项是模型路径和端口。

# 通用启动骨架，具体参数名以所选程序为准
openai-compat-server \
  `--model` /path/to/chatglm3-6b 或 `--model-name` internlm2-chat \
  `--port` 8000 \
  `--host` 0.0.0.0

建议先不加鉴权参数启动一次，确认服务能起来并打印模型加载日志。如果模型路径错误，服务通常会在启动阶段报文件不存在或权重格式不匹配，而不是等到请求时才报错。启动成功后用本地回环地址测试连通性，不要一开始就绑定 0.0.0.0 暴露到局域网。

配置服务端口与虚拟密钥

客户端请求 OpenAI 接口时需要带 Authorization 头，但本地模型本身没有 OpenAI 的密钥体系，所以兼容层会提供一个虚拟密钥。这个密钥只用于通过本地服务的鉴权检查，不需要与任何云服务对应。设置方式一般是环境变量或启动参数，例如 OpenAI_API_KEY 和 OPENAI_API_BASE。

export OPENAI_API_KEY=sk-local-test-key
export OPENAI_API_BASE=http://127.0.0.1:8000/v1

设置后先用 curl 做连通性测试，确认端口、密钥和路由都正常。以下请求同时覆盖鉴权和对话补全路由，如果返回包含 choices 的 JSON，说明服务层工作正常。

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-local-test-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "internlm2-chat",
    "messages": [{"role": "user", "content": "你好"}]
  }'

测试时注意 curl 返回的 HTTP 状态码。401 表示密钥不对，404 表示路由或 model 不匹配，500 表示服务端推理环节出错。每次修改密钥或端口后都要重新 curl 一次，确认新配置生效。

改写客户端 SDK 的 base_url 和 model 字段

现有 Python OpenAI SDK 代码通常只需要改两处：构造 OpenAI 客户端时的 base_url，以及每次请求里的 model 字段。保留 api_key 字段，但值换成前面设置的虚拟密钥。超时参数建议显式设置，默认超时在某些长文本生成场景下容易误报超时。

from openai import OpenAI

client = OpenAI(
    api_key="sk-local-test-key",
    base_url="http://127.0.0.1:8000/v1",
    timeout=60.0,  # 或根据模型生成长度适当调大
)

response = client.chat.completions.create(
    model="internlm2-chat",
    messages=[{"role": "user", "content": "介绍一下你自己"}],
)
print(response.choices[0].message.content)

model 字段的值必须与兼容服务启动时指定的模型名称一致。如果服务层支持模型别名，可以在启动参数中配置；否则客户端传错名称，服务端会返回 model not found 或类似错误。超时设置需要结合模型推理速度和生成长度判断，先设置 60 秒试跑。

对齐文本补全与对话补全两种调用格式

OpenAI 兼容接口有两条常见路由：/v1/chat/completions 和 /v1/completions。前者的请求体使用 messages 列表，后者使用 prompt 字符串。两者返回结构也不一样，客户端不能混用。

# chat.completions 请求体
{
  "model": "internlm2-chat",
  "messages": [
    {"role": "system", "content": "你是一个助手"},
    {"role": "user", "content": "写一段代码"}
  ],
  "temperature": 0.7
}

# completions 请求体
{
  "model": "internlm2-chat",
  "prompt": "写一段代码",
  "max_tokens": 512,
  "temperature": 0.7
}

书生·浦语这类对话模型通常建议使用 chat.completions，因为训练目标就是多轮对话。如果要用 completions 路由，需要先确认兼容层是否把 prompt 自动组装成对话格式。部分服务层会忽略 temperature 或 max_tokens，具体行为要看服务端日志或返回参数。

用日志定位 401/404/500 的具体环节

配置完成后如果请求失败，不要只盯着客户端报错，先去服务端看日志。兼容服务通常会把每次请求的路由、鉴权结果、模型返回耗时和错误堆栈打印到终端或日志文件。

401：检查 Authorization 头是否带 Bearer 前缀，虚拟密钥是否与启动时设置的一致。
404：检查 base_url 是否包含 /v1，模型名是否与服务端注册的名称一致，路由是 chat/completions 还是 completions。
500：查看服务端是否出现 CUDA out of memory、段错误或 Python 异常。如果日志中看到段错误，优先排查模型版本与依赖库版本是否匹配。

定位时可以先在服务端日志里搜索请求时间点附近的信息。如果日志显示请求已进入模型推理但随后崩溃，说明协议层正常，问题在推理环境。如果日志里连请求记录都没有，说明请求根本没到达服务端，需要检查端口监听和防火墙。

书生·浦语 本地模型接入 OpenAI 兼容接口的配置方法