Windows 环境下用 LiteLLM 桥接 OpenAI `messages/chat` 接口到 `/v1/responses` 的操作手册

本文目标：

你的上游接口只支持 OpenAI 风格的 messages / /v1/chat/completions
你希望在 Windows 本机 部署一个 LiteLLM Proxy
让客户端通过 /v1/responses 访问
由 LiteLLM 自动桥接到上游的 /v1/chat/completions

一、最终效果

部署完成后，请求链路如下：

TEXT

客户端 / Codex / OpenAI SDK
        |
        v
http://127.0.0.1:4000/v1/responses
        |
        v
LiteLLM Proxy
        |
        v
你的上游接口
http://127.0.0.1:8000/v1/chat/completions

二、前提条件

你需要准备好以下内容：

Windows 10 或 Windows 11
Python 3.10 或更高版本
一个已经可用的上游接口，例如：

TEXT

http://127.0.0.1:8000/v1/chat/completions

上游接口支持 OpenAI 风格请求体，例如：

JSON

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ]
}

一个上游 API Key
如果上游不校验，也可以先随便填一个字符串，例如 sk-upstream

三、步骤 1：安装 Python

从 Python 官网安装 Windows 版 Python。

安装时务必勾选：

TEXT

Add Python to PATH

安装完成后，打开 PowerShell，执行：

POWERSHELL

python --version
pip --version

如果能正常看到版本号，就说明 Python 已安装成功。

四、步骤 2：创建工作目录

打开 PowerShell，执行：

POWERSHELL

mkdir C:\litellm-proxy
cd C:\litellm-proxy

五、步骤 3：创建虚拟环境并安装 LiteLLM

在 PowerShell 中执行以下命令：

POWERSHELL

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install "litellm[proxy]"

如果激活脚本被 PowerShell 拒绝执行

先执行：

POWERSHELL

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

然后重新激活：

POWERSHELL

.\.venv\Scripts\Activate.ps1

六、步骤 4：先测试你的上游 `chat/completions` 接口是否可用

在接入 LiteLLM 之前，必须先确认你的上游接口本身是通的。

假设你的上游接口是：

TEXT

http://127.0.0.1:8000/v1/chat/completions

请执行以下 PowerShell 命令：

POWERSHELL

$body = @{
  model = "gpt-4o-mini"
  messages = @(
    @{
      role = "user"
      content = "只回复：ok"
    }
  )
} | ConvertTo-Json -Depth 10

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8000/v1/chat/completions" `
  -Method Post `
  -Headers @{
    "Authorization" = "Bearer sk-upstream"
    "Content-Type"  = "application/json"
  } `
  -Body $body

你需要修改的地方

把下面两项改成你自己的真实值：

POWERSHELL

model = "gpt-4o-mini"

改成你的上游真实模型名。

POWERSHELL

"Authorization" = "Bearer sk-upstream"

改成你的上游真实 key。
如果上游不校验 key，也可以暂时保留任意值。

成功标准

返回结果中能看到类似下面字段：

JSON

{
  "choices": [
    {
      "message": {
        "content": "ok"
      }
    }
  ]
}

只要这一步不通，后面的桥接一定不会成功。

七、步骤 5：创建 `config.yaml`

在目录：

TEXT

C:\litellm-proxy

中新建文件：

TEXT

config.yaml

写入以下内容：

YAML

model_list:
  - model_name: my-bridge-model
    litellm_params:
      model: openai/gpt-4o-mini
      api_base: http://127.0.0.1:8000
      api_key: sk-upstream

general_settings:
  master_key: sk-litellm-local

八、步骤 6：理解 `config.yaml` 每一项是什么意思

1）`model_name`

YAML

model_name: my-bridge-model

这是客户端请求 LiteLLM 时使用的模型名。

例如你调用 LiteLLM 时，请求里会写：

JSON

{
  "model": "my-bridge-model",
  "input": "你好"
}

2）`litellm_params.model`

YAML

model: openai/gpt-4o-mini

这是 LiteLLM 实际转发给上游时使用的模型标识。

注意格式必须是：

TEXT

openai/真实模型名

例如：

YAML

model: openai/gpt-4o-mini

如果你的上游真实模型名是：

TEXT

my-model

则写成：

YAML

model: openai/my-model

3）`api_base`

YAML

api_base: http://127.0.0.1:8000

这里只写上游主地址，不要把完整接口路径写进去。

正确写法：

YAML

api_base: http://127.0.0.1:8000

错误写法：

YAML

api_base: http://127.0.0.1:8000/v1
api_base: http://127.0.0.1:8000/v1/chat/completions

4）`api_key`

YAML

api_key: sk-upstream

这是 LiteLLM 调上游时用的 key。

如果你的上游需要 key，就填真实值。
如果你的上游不校验，可以先写任意字符串。

5）`master_key`

YAML

master_key: sk-litellm-local

这是你访问 LiteLLM Proxy 自己时要带的 Bearer Token。

后面你调用 LiteLLM 时，请求头里要写：

TEXT

Authorization: Bearer sk-litellm-local

九、步骤 7：启动 LiteLLM Proxy

在 PowerShell 中执行：

POWERSHELL

cd C:\litellm-proxy
.\.venv\Scripts\Activate.ps1
litellm --config .\config.yaml --detailed_debug

启动成功后，LiteLLM 通常会监听：

TEXT

http://127.0.0.1:4000

十、步骤 8：先测试 LiteLLM 的 `/v1/chat/completions`

这一步用于确认：

LiteLLM 已成功读取 config.yaml
LiteLLM 能成功调用上游
model_name 配置正确

执行：

POWERSHELL

$body = @{
  model = "my-bridge-model"
  messages = @(
    @{
      role = "user"
      content = "只回复：bridge chat ok"
    }
  )
} | ConvertTo-Json -Depth 10

Invoke-RestMethod `
  -Uri "http://127.0.0.1:4000/v1/chat/completions" `
  -Method Post `
  -Headers @{
    "Authorization" = "Bearer sk-litellm-local"
    "Content-Type"  = "application/json"
  } `
  -Body $body

成功标准

返回中能看到正常文本回复，例如：

TEXT

bridge chat ok

说明普通 chat 转发已经通了。

十一、步骤 9：测试 LiteLLM 的 `/v1/responses`

这一步才是最终目标：让客户端访问 /v1/responses，由 LiteLLM 自动桥接到上游 chat/completions。

执行：

POWERSHELL

$body = @{
  model = "my-bridge-model"
  input = "只回复：bridge responses ok"
} | ConvertTo-Json -Depth 10

Invoke-RestMethod `
  -Uri "http://127.0.0.1:4000/v1/responses" `
  -Method Post `
  -Headers @{
    "Authorization" = "Bearer sk-litellm-local"
    "Content-Type"  = "application/json"
  } `
  -Body $body

成功标准

返回中能看到对应文本内容，表达出：

TEXT

bridge responses ok

这就说明：

客户端请求的是 /v1/responses
LiteLLM 已成功桥接到你的上游 /v1/chat/completions

十二、完整示例配置

假设你的真实上游环境如下：

上游主地址：

TEXT

http://127.0.0.1:8000

上游接口：

TEXT

POST /v1/chat/completions

上游模型名：

TEXT

gpt-4o-mini

上游 key：

TEXT

sk-upstream

那么你最终的 config.yaml 如下：

YAML

model_list:
  - model_name: my-bridge-model
    litellm_params:
      model: openai/gpt-4o-mini
      api_base: http://127.0.0.1:8000
      api_key: sk-upstream

general_settings:
  master_key: sk-litellm-local

十三、完整测试命令汇总

1）测试上游接口

POWERSHELL

$body = @{
  model = "gpt-4o-mini"
  messages = @(
    @{
      role = "user"
      content = "只回复：ok"
    }
  )
} | ConvertTo-Json -Depth 10

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8000/v1/chat/completions" `
  -Method Post `
  -Headers @{
    "Authorization" = "Bearer sk-upstream"
    "Content-Type"  = "application/json"
  } `
  -Body $body

2）启动 LiteLLM

POWERSHELL

cd C:\litellm-proxy
.\.venv\Scripts\Activate.ps1
litellm --config .\config.yaml --detailed_debug

3）测试 LiteLLM 的 chat 接口

POWERSHELL

$body = @{
  model = "my-bridge-model"
  messages = @(
    @{
      role = "user"
      content = "只回复：bridge chat ok"
    }
  )
} | ConvertTo-Json -Depth 10

Invoke-RestMethod `
  -Uri "http://127.0.0.1:4000/v1/chat/completions" `
  -Method Post `
  -Headers @{
    "Authorization" = "Bearer sk-litellm-local"
    "Content-Type"  = "application/json"
  } `
  -Body $body

4）测试 LiteLLM 的 responses 接口

POWERSHELL

$body = @{
  model = "my-bridge-model"
  input = "只回复：bridge responses ok"
} | ConvertTo-Json -Depth 10

Invoke-RestMethod `
  -Uri "http://127.0.0.1:4000/v1/responses" `
  -Method Post `
  -Headers @{
    "Authorization" = "Bearer sk-litellm-local"
    "Content-Type"  = "application/json"
  } `
  -Body $body

十四、常见报错与排查

1）报错：`model not found`

原因通常是请求中的：

JSON

{
  "model": "my-bridge-model"
}

与 config.yaml 里的：

YAML

model_name: my-bridge-model

不一致。

2）报错：上游 404

通常是 api_base 写错了。

正确写法：

YAML

api_base: http://127.0.0.1:8000

错误写法：

YAML

api_base: http://127.0.0.1:8000/v1
api_base: http://127.0.0.1:8000/v1/chat/completions

3）报错：上游 401

说明 LiteLLM 调用上游时鉴权失败。

检查 config.yaml：

YAML

api_key: sk-upstream

把它改成你的真实上游 key。

4）报错：LiteLLM 401

说明你调用 LiteLLM 时使用的 Bearer Token 不对。

检查请求头：

TEXT

Authorization: Bearer sk-litellm-local

它必须与 config.yaml 里的：

YAML

general_settings:
  master_key: sk-litellm-local

一致。

5）`/chat/completions` 能通，但 `/responses` 表现不符合预期

这属于桥接方案的自然限制。

原因是：

上游原生支持的是 /v1/chat/completions
LiteLLM 只是把 /v1/responses 桥接过去
某些 Responses 原生能力与 chat 接口并不能完全等价

如果只是普通文本问答，通常没有问题。
如果涉及更复杂的原生 Responses 语义，就可能存在差异。

十五、给 Codex 使用的配置示例

如果你想让 Codex 连接这个本地 LiteLLM，可以参考下面的 config.toml：

TOML

model = "my-bridge-model"
model_provider = "litellm_local"

[model_providers.litellm_local]
name = "LiteLLM Local"
base_url = "http://127.0.0.1:4000/v1"
env_key = "LITELLM_PROXY_API_KEY"
wire_api = "responses"

然后在 PowerShell 中设置环境变量：

POWERSHELL

$env:LITELLM_PROXY_API_KEY = "sk-litellm-local"

十六、最关键的三个点

先单独测试你的上游 /v1/chat/completions 是否可用
config.yaml 中的 litellm_params.model 必须写成 openai/真实模型名
api_base 只能写上游主地址，不能拼 /v1 或 /v1/chat/completions

十七、一份最小可直接复用的模板

`config.yaml`

YAML

model_list:
  - model_name: my-bridge-model
    litellm_params:
      model: openai/gpt-4o-mini
      api_base: http://127.0.0.1:8000
      api_key: sk-upstream

general_settings:
  master_key: sk-litellm-local

启动命令

POWERSHELL

cd C:\litellm-proxy
.\.venv\Scripts\Activate.ps1
litellm --config .\config.yaml --detailed_debug

最终测试命令

POWERSHELL

$body = @{
  model = "my-bridge-model"
  input = "只回复：hello from responses bridge"
} | ConvertTo-Json -Depth 10

Invoke-RestMethod `
  -Uri "http://127.0.0.1:4000/v1/responses" `
  -Method Post `
  -Headers @{
    "Authorization" = "Bearer sk-litellm-local"
    "Content-Type"  = "application/json"
  } `
  -Body $body

Codex协议转换适配

Windows 环境下用 LiteLLM 桥接 OpenAI messages/chat 接口到 /v1/responses 的操作手册

一、最终效果

二、前提条件

三、步骤 1：安装 Python

四、步骤 2：创建工作目录

五、步骤 3：创建虚拟环境并安装 LiteLLM

如果激活脚本被 PowerShell 拒绝执行

六、步骤 4：先测试你的上游 chat/completions 接口是否可用

你需要修改的地方

成功标准

七、步骤 5：创建 config.yaml

八、步骤 6：理解 config.yaml 每一项是什么意思

1）model_name

2）litellm_params.model

3）api_base

4）api_key

5）master_key

九、步骤 7：启动 LiteLLM Proxy

十、步骤 8：先测试 LiteLLM 的 /v1/chat/completions

成功标准

十一、步骤 9：测试 LiteLLM 的 /v1/responses

成功标准

十二、完整示例配置

十三、完整测试命令汇总

1）测试上游接口

2）启动 LiteLLM

3）测试 LiteLLM 的 chat 接口

4）测试 LiteLLM 的 responses 接口

十四、常见报错与排查

1）报错：model not found

2）报错：上游 404

3）报错：上游 401

4）报错：LiteLLM 401

5）/chat/completions 能通，但 /responses 表现不符合预期

十五、给 Codex 使用的配置示例

十六、最关键的三个点

十七、一份最小可直接复用的模板

config.yaml

启动命令

最终测试命令

评论交流

Windows 环境下用 LiteLLM 桥接 OpenAI `messages/chat` 接口到 `/v1/responses` 的操作手册

六、步骤 4：先测试你的上游 `chat/completions` 接口是否可用

七、步骤 5：创建 `config.yaml`

八、步骤 6：理解 `config.yaml` 每一项是什么意思

1）`model_name`

2）`litellm_params.model`

3）`api_base`

4）`api_key`

5）`master_key`

十、步骤 8：先测试 LiteLLM 的 `/v1/chat/completions`

十一、步骤 9：测试 LiteLLM 的 `/v1/responses`

1）报错：`model not found`

5）`/chat/completions` 能通，但 `/responses` 表现不符合预期

`config.yaml`