Python 调试 Litellm 本地大模型接口：模型列表与对话接口实操踩坑记录

最近在本地搭建 Litellm 大模型统一代理服务，通过本地接口调用私有化部署的各类大模型。实操中完成两个核心接口调试：模型列表查询、对话补全调用。过程踩了一些接口格式、请求头相关的坑，整理完整调试代码、问题排查思路，给同样在本地私有化部署大模型的同学参考。

一、环境与服务基础说明

本次实操基于单机部署的 Litellm 代理服务。

服务访问地址：http://[内网IP]:[服务端口]

鉴权方式：Bearer Token 鉴权，代理密钥：[自定义密钥]

调试两个 OpenAI 兼容接口：

/v1/models：GET，查询当前代理加载的模型清单
/v1/chat/completions：POST，对话推理接口

调试工具：Python3 内置库 urllib.request + json，不需要安装额外第三方包，开箱即可调试接口，适合快速验证服务可用性。

二、实操一：查询已部署模型列表

1. 完整调试代码

GET 请求获取模型列表，带上鉴权头，设置较短超时防止卡死：

复制代码

python3 -c "
import urllib.request
req=urllib.request.Request('http://[内网IP]:[服务端口]/v1/models',headers={'Authorization':'Bearer [自定义密钥]'})
print(urllib.request.urlopen(req,timeout=5).read().decode()[:500])
"

2. 踩坑问题：手写地址容易出错

最开始调试的时候一直连接失败，排查很久发现是手动输入地址时，数字、字母混淆，端口写错，直接导致无法访问服务。

避坑提醒：内网调试接口，IP、端口、路径尽量复制粘贴，不要手敲，非常容易出现 0/o、1/l 这类字符混淆。

3. 正常返回结果

修正地址之后，接口正常返回模型列表。可以看到代理已经加载好对话模型、向量模型、代码模型等。

这一步主要用来验证两件事：

Litellm 代理服务正常启动，端口监听正常
鉴权密钥有效，可以正常访问接口

三、实操二：调用对话接口，发起模型问答

确认模型列表接口通了之后，继续测试核心对话接口，调用开源对话模型做基础问答测试。

1. 完整调试代码

复制代码

python3 -c "
import urllib.request, json
# 请求头：鉴权 + 声明请求体是JSON
H={'Authorization':'Bearer [自定义密钥]','Content-Type':'application/json'}
base='http://[内网IP]:[服务端口]'
# OpenAI兼容格式请求体
data=json.dumps({
    'model':'qwen3.5',
    'messages':[{'role':'user','content':'你好'}],
    'max_tokens':3333
}).encode()
# POST请求，推理耗时更长，超时时间调大
r=urllib.request.urlopen(urllib.request.Request(base+'/v1/chat/completions',data=data,headers=H),timeout=60).read().decode()
print(r[:300])
"

2. 接口关键要点

请求方法区分：模型列表是 GET；对话补全是 POST，必须传 JSON body
POST 请求必须带上 Content-Type: application/json，否则服务无法解析参数
模型推理需要时间，对话接口超时要设置大一点，不要复用查询接口的短超时
请求体格式遵循 OpenAI 标准，Litellm 会把请求转发给后端实际模型

3. 接口成功返回

代码执行后，模型正常返回回答，返回 JSON 结构包含模型名称、生成内容、token 用量等字段，完全兼容 OpenAI 接口规范。

Litellm 的价值就在这里：后端不管接入什么开源模型，对外统一一套接口，上层应用不用针对不同模型改代码。

四、调试总结 & 避坑清单

✅ 本次实操成果

验证 Litellm 代理服务连通性，鉴权配置生效
掌握 /v1/models 和 /v1/chat/completions 两个核心兼容接口调用方式
成功调用开源对话模型完成问答推理

⚠️ 避坑汇总

IP、端口、接口路径尽量复制，不要手动输入，极易字符混淆
GET 和 POST 接口不要混用；POST 请求必须携带Content-Type: application/json
对话推理接口超时时间要拉长，推理慢的模型很容易超时断开
Token 鉴权头部格式：Bearer 密钥，Bearer 后面有空格，少空格直接鉴权失败

五、拓展方向

基础调通之后，可以继续做这些扩展：

给代码加上异常捕获（try except），处理连接超时、鉴权失败、服务 500 报错
封装成通用函数，方便批量测试多个模型
增加参数调优：temperature、top_p、stream 流式输出
对接上层应用，利用 Litellm 统一代理管理多模型路由、负载均衡

本文仅演示 Litellm 接口调试方法，内网私有化部署请做好网络访问控制，不要把代理服务直接暴露公网。