Mage 接入 OpenAI 兼容接口的鉴权与路由配置

如果现在要直接使用OpenAI SDK调用Mage服务，需要的配置可以概括为：确认Mage提供兼容端点、设置base_url和api_key、确保路由能转发请求，然后验证连通。核心是让SDK发出的请求经过鉴权和路由，最终命中Mage的推理服务。

如果Mage暴露了OpenAI兼容的/v1接口，接入方式与普通OpenAI客户端一致：把base_url指向Mage端点，api_key填写Mage认可的标识，模型名按要求映射。接入前先用curl探测/v1/models，再配置SDK与网关路由；验证时以实际HTTP状态码和响应体为准。不同Mage版本可能对路径、密钥格式、模型参数支持不一致，需要结合环境确认。

确认Mage服务是否暴露兼容API

不能假设Mage默认提供OpenAI兼容接口。先看Mage的部署文档或启动日志，确认是否包含“OpenAI compatible”或/v1路径说明。也可以用文本请求试探：向Mage服务的根目录发送GET /v1/models，看是否返回模型列表。

curl -s http://mage-host:8000/v1/models \
  -H "Authorization: Bearer sk-invalid-key"

如果返回的是JSON数组，例如{"data":[{"id":"..."}]}，说明该端点可用。如果返回404，需要检查是否安装或启用了兼容层插件，或者路径是否有前缀。

设置base_url、api_key与模型映射

确认Mage兼容端点后，在OpenAI SDK中设置三个关键参数：base_url、api_key和模型名。以Python为例：

from openai import OpenAI
client = OpenAI(
    base_url="http://mage-host:8000/v1",
    api_key="your-mage-api-key",
)
response = client.chat.completions.create(
    model="mage-model-1",
    messages=[{"role": "user", "content": "hello"}],
)

这里的api_key可能是Mage服务内部校验的固定占位符，也可能是通过管理接口生成的密钥。模型名需要与Mage中实际部署的模型名称一致；如果客户端默认用gpt-3.5-turbo，Mage可能不认识，会返回模型不存在。因此需要在SDK调用中明确指定模型名，或在网关层做模型名映射。

配置路由规则将请求转发到Mage后端

如果客户端不能直接访问Mage主机，或需要统一入口，可以在反向代理中配置路由。建议将/v1开头的请求全部转发到Mage后端，确保路径不被吞掉。Nginx示例：

location /v1/ {
    proxy_pass http://mage-backend:8000;
    proxy_set_header Host $host;
    proxy_set_header Authorization $http_authorization;
}

注意proxy_pass不带尾斜杠时，/v1/会原样传给后端；带尾斜杠时会替换为/，需要根据Mage实际路由确定。如果是网关类工具，通常只需要创建一条服务，把OpenAI兼容的路径映射到Mage后端，并在请求头中透传 Authorization。

处理鉴权失败与模型不存在等错误

接入过程中最常见的报错集中在HTTP状态码和错误体上。遇到401时，先检查Authorization头是否真的被网关转发，以及api_key是否被Mage接受。遇到404时，区分是端点路径不存在还是模型名称不存在：可以发送一个极小的chat请求，从响应体中的error字段分辨。

{"error": {"message": "The model `gpt-3.5-turbo` does not exist", "type": "invalid_request_error", "code": "model_not_found"}}

如果是模型不存在，把SDK的model参数改成Mage可用的名称，或在网关添加重写规则。如果返回401，Mage日志中会记录具体鉴权来源，需要核对密钥是否配置在正确位置。

验证连通性并返回多模态响应

配置完成后，用curl模拟一次请求，直接观察返回内容。先发单文本请求：

curl -s http://mage-host/v1/chat/completions \
  -H "Authorization: Bearer your-mage-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"mage-model-1","messages":[{"role":"user","content":"test"}]}'

看到HTTP 200且choices[0].message.content有返回，即说明基本链路连通。若要验证多模态，需要在消息中传入图片内容，并确认模型支持视觉输入。例如：

-d '{"model":"mage-vision","messages":[{"role":"user","content":[{"type":"text","text":"describe this image"},{"type":"image_url","image_url":{"url":"https://example.com/cat.png"}}]}]}'

如果Mage支持图像生成，还可能有/v1/images/generations端点。检查响应的data数组是否包含url或b64_json字段，以及HTTP状态码是否为200。以实际返回为准，不要只依赖状态码。