企业官网建设流程全解析

做AI应用开发这行，最烦的不是模型效果不够好，而是每次要接入一个新的模型服务，都得重新读一遍文档、重新封装一遍请求、重新调一遍鉴权和超时参数。前阵子我接了个模拟项目X，需要把同一个功能分别接到好几家不同的模型供应商上做效果对比，A厂商一套鉴权方式，B厂商一套返回格式，C厂商的流式输出又跟别人不一样，光是维护那堆调用代码就让人头大。后来我把项目里所有模型请求统一改走litellm，事情一下子简单了。

litellm这个工具，说白了就是一个模型调用的统一网关，它把市面上主流的大模型API请求方式，统一收敛成一套标准接口，你只需要写一份代码，就能在不同模型之间随意切换。它还附带一个代理服务，可以在团队内部共享模型访问能力，顺带把鉴权、限流、成本统计这些杂活一起干了。如果你是做应用开发、AI产品原型、或者是需要在多个模型之间做对比测试的人，这篇文章应该能帮你省下不少时间。我会把实际项目中怎么用它、哪些地方容易掉坑、参数怎么调，都拆开来讲清楚。

1. 先搞清楚litellm解决的是什么问题

1.1 多模型接入的混乱现状

现在的模型服务生态非常割裂，各家有各家的HTTP接口规范。有的走兼容格式，有的自己定义了一套消息结构，有的返回纯文本，有的返回带格式的富文本。你写业务代码的时候，一旦要接两个以上的模型，就不得不维护两套以上的请求封装、错误重试逻辑和数据处理逻辑。更麻烦的是，不同厂商对token数、上下文长度、超时时间的限制也都不一样，这些差异要是散落在业务代码里，到了后面根本没法维护。

我自己最早是写了一个工具类，把各个厂商的请求封装成统一的函数。一开始还行，但很快问题就出来了：新增一个模型就要改工具类，改完怕影响老模型；某个厂商改了接口版本，又要全局排查调用点；想在两个模型之间做A/B对比，还得写一堆胶水代码。这种自己造的轮子，在模型数量少的时候勉强能用，一旦超过两三个，就开始失控。

1.2 统一网关的核心思路

litellm的处理方式说起来很简单，就是把“模型调用”这件事分成两层。第一层是SDK，你直接调用它提供的统一接口，传入模型名和消息内容，剩下的事情它帮你搞定。第二层是代理服务，你在服务器上跑一个轻量级网关，所有模型请求都打到这个网关，由网关去访问各个模型厂商，然后统一返回。

这个设计的好处在于，业务代码只依赖litellm这一套接口，底层接的是哪家模型、用的什么鉴权方式，业务层完全不用关心。哪天想换个模型做对比，改一行配置就行，业务代码一行都不用动。这个不光是省事的问题，更重要的是把“模型接入”这个容易变动的部分，从业务代码里彻底隔离出去了。

1.3 为什么不自研一个封装层

有人可能会问：既然核心思路是加一层封装，我自己写个工具类不也行吗？实话实说，如果你只接一个模型、只在本地脚本里跑一跑，那确实自己写更直接。但只要超过一个模型，或者需要多人协作，自研封装的成本就很高。

litellm里凝结了很多实际踩坑后才有的处理，比如不同厂商对重试次数的建议、对上下文字段名的解析差异、对工具调用格式的兼容处理、以及token统计口径。这些东西如果自己一行行去查文档实现，至少要折腾一两周。而litellm是现成的，我只需要把模型配置填进去就行。做技术选型的时候，能用成熟的开源轮子解决的问题，就别重复造轮子，这是我在这个项目里最深的体会之一。

2. 核心功能拆解：SDK加代理服务的两层设计

2.1 SDK层：在代码里直接切换模型

litellm用起来最直观的一点，就是它把整套请求入口收敛成了几个函数，最核心的是completion函数。以前我接不同模型要写不同代码，现在只改一个model参数就行。模型名的格式也有讲究，前半段指定厂商，后半段指定具体模型名，中间用斜杠分隔。

import litellm response = litellm.completion( model="provider_a/model-a", messages=[{"role": "user", "content": "你好，帮我写一段Python代码"}], temperature=0.7 ) print(response.choices[0].message.content)

这段代码换成另一家模型，只需要把model改成provider_b/model-b。冷热切换模型做对比，在这个体系下就变成改字符串的事。密钥管理也简单，litellm支持从环境变量读取各家API Key，你只要把Key配置到环境里，代码里不需要再出现任何密钥。

export PROVIDER_A_API_KEY="sk-xxxx" export PROVIDER_B_API_KEY="sk-xxxx"

当然，SDK层不止completion这一种能力，它还支持embedding接口、批量请求、流式输出，以及对一些模型专有参数的处理。流式输出是很多应用场景里的硬需求，litellm对此做了兼容，你调用的时候加上stream=True，然后遍历返回的事件流就行。

response = litellm.completion( model="provider_a/model-a", messages=[{"role": "user", "content": "讲个冷笑话"}], stream=True ) for chunk in response: print(chunk.choices[0].delta.content, end="")

2.2 代理服务层：团队共享的模型网关

SDK层解决的是“我自己的代码怎么调模型”，但实际项目里往往还要解决“团队怎么共用一套模型配置”。如果每个人都拿自己的密钥去调模型，密钥管理混乱不说，几个Key很快就会被限流，成本支出也没法统一看。所以litellm还带了一个代理服务，你可以把它理解成一个中间人，它统一持有模型密钥，对外暴露一个标准接口，团队里所有人都请求这个接口。

代理服务的使用场景我列一下，基本就是下面这几种：

• 团队协作时，统一管理模型密钥，成员不直接接触厂商密钥。
• 在网关层做限流、预算控制，防止某个实验任务把账单拉爆。
• 把多个模型的路由、重试、fallback策略收敛到一个地方统一管理。
• 记录所有请求日志和费用开销，方便月底对账和成本分析。

部署代理服务并不复杂，装好依赖之后，写一个配置文件，启动一个进程就行。团队其他人只需要把代码里的基础地址指向这个代理服务，密钥换成网关分配的一个Key，就能开始调用。

2.3 模型路由与fallback机制

litellm另外一个我觉得特别实用的功能，是在代理层做模型路由和failover。比如你可以在配置里声明：主模型用A厂商的model-a，如果它超时或报错，就自动切换到B厂商的model-b。这个机制对稳定性要求较高的线上应用极其有用，因为任何一家模型服务的可用性都不可能永远100%，与其在业务代码里写一堆重试逻辑，不如在网关层统一处理。

配置方式是在模型列表里给同一个对外模型名绑定多个实际供应商，并设置优先级和权重。我举一个简化配置：

model_list: - model_name: unified_model litellm_params: model: provider_a/model-a api_key: os.environ/PROVIDER_A_API_KEY - model_name: unified_model litellm_params: model: provider_b/model-b api_key: os.environ/PROVIDER_B_API_KEY

这样配置之后，所有请求打到unified_model，网关会优先尝试第一个模型，如果失败就转第二个。对调用方来说，整个过程是透明的，业务代码甚至都不知道背后发生过切换。这个能力单独拿出来说，已经值回接入成本了。

3. 实操：从装依赖到跑通第一个请求

3.1 安装依赖

首先是把litellm装到环境里。官方推荐直接通过pip安装，安装的时候可以带上proxy的扩展依赖，这样代理服务需要的那部分组件也会一并装上。

pip install "litellm[proxy]"

装完之后，可以检查一下版本，确认安装成功。

python -c "import litellm; print(litellm.__version__)"

按我自己的经验，建议装在独立的虚拟环境里，不要直接装到系统全局的Python环境，因为litellm的依赖版本变化比较快，隔离环境能避免和其他项目形成冲突。

3.2 基础配置：把多个密钥收进一个入口

安装完之后，我们要把模型密钥配好。SDK模式比较简单，直接在环境变量里声明各个厂商的Key就行。代理服务模式的配置稍微复杂一点，需要写一个YAML配置文件，把要用到的模型和对应的密钥来源写清楚。

model_list: - model_name: provider_a_model litellm_params: model: provider_a/model-a api_key: os.environ/PROVIDER_A_API_KEY - model_name: provider_b_model litellm_params: model: provider_b/model-b api_key: os.environ/PROVIDER_B_API_KEY litellm_settings: drop_params: true set_verbose: true general_settings: master_key: sk-my-master-key

这里有几个点要注意。model_name是自己定义的对内名称，后续所有人都通过这个名字来请求；litellm_params里写的是真实模型的提供商和模型名。master_key是网关的管理员密钥，首次启动之后，用它来生成团队里其他人用的一组虚拟密钥。drop_params: true这个配置也很关键，它的作用是如果某个请求参数是当前模型不支持的，干脆直接丢掉，避免因为多余参数而导致请求报错。

3.3 用SDK方式跑通第一个请求

配置好Key之后，可以先用SDK的最简模式跑通链路。写一个Python脚本，直接调用litellm.completion，用provider_a/model-a请求一次，看能不能正常返回结果。

import os import litellm os.environ["PROVIDER_A_API_KEY"] = "sk-xxxx" response = litellm.completion( model="provider_a/model-a", messages=[ {"role": "system", "content": "你是一个简洁的助手"}, {"role": "user", "content": "用一句话解释什么是统一网关"} ] ) print(response.choices[0].message.content)

跑通这一步，说明SDK层的链路没问题。如果到这里报错，先检查环境和网络连通性，这类问题一般是环境变量没加载进去或者是网络方向不通。

3.4 启动代理服务并验证

SDK链路通了之后，我们再起代理服务。执行命令很简单，把刚才写好的配置文件传给litellm即可。

litellm --config config.yaml --port 4000

启动成功后，代理服务会在本地4000端口监听。验证方式很直接，用curl发一个请求过去，看能不能得到模型返回。

curl --location 'http://localhost:4000/v1/chat/completions' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sk-my-master-key' \ --data '{ "model": "provider_a_model", "messages": [ {"role": "user", "content": "你好"} ] }'

确认能正常返回之后，团队里其他人就可以把这个地址当作模型服务的入口来用了。他们的代码只需要配置base_url为这个代理地址，密钥设置为网关分配的虚拟Key，剩下的模型路由、密钥管理都由网关处理。

3.5 业务代码里的标准调用方式

代理服务配好之后，业务侧代码反而更简单了。不管底层是哪个模型，代码里都是同一套写法：

from openai import OpenAI client = OpenAI( base_url="http://localhost:4000/v1", api_key="sk-team-key" ) response = client.chat.completions.create( model="unified_model", messages=[{"role": "user", "content": "你好"}] ) print(response.choices[0].message.content)

看到这个写法的朋友应该能感觉到，这套接口风格和业界常见的接口规范是一模一样的，所以它接入业务系统的时候几乎是无痛的。你原来代码怎么写的，现在就怎么写，只是把base_url指到自己的网关。

4. 真实项目里的踩坑记录与排查方法

4.1 超时与重试的调参经验

我在实际用的时候，踩过最冤的一个坑就是超时。默认情况下，有些调用会等很久才返回，尤其是生成式模型的响应本来就慢，一旦网络状况不稳定，前端体验就很差。

解决办法是在配置里显式声明超时时间，不要依赖默认值。SDK模式可以传timeout参数，代理服务模式可以在配置文件的litellm_settings里设置全局超时。

litellm_settings: request_timeout: 60 num_retries: 3 retry_after: 5

重试的力度也要控制好，不要一味增加重试次数，因为模型服务一旦真的出问题，重试多少次都没意义，反而会拖慢整个链路的响应。我一般是重试1到2次，配合fallback机制来兜底，而不是无脑重试。

4.2 上下文长度与token计算陷阱

第二个坑是上下文长度。不同模型能处理的上下文长度不同，如果你传了太长的输入，模型会直接拒绝请求。litellm内部有一套token计算逻辑，但它的估算有时偏乐观，尤其是在处理中文内容时。

我的建议是在应用层自己先做一次长度检查。反正模型服务商一般都有返回token使用情况的字段，根据历史请求统计一个安全的输入长度阈值，超了就提前截断或者提示用户，不要在模型端报错了才处理。还有一点，不要一次性把所有历史会话都塞进去，该做摘要就做摘要，这样既省token也避免超限。

4.3 流式输出和参数格式不兼容的问题

用流式输出的时候，我也遇到过一个比较恼人的问题。不同模型服务商返回的数据结构不一致，有的在delta里带content，有的在choices里返回完整消息，有的还会额外推送一些事件类型。litellm虽然做了兼容，但在代理模式下，有一些厂商的复杂调用格式仍然不能完全转换过来。

我当时的处理方法比较土但有效：在调用时打开日志，把原始请求和返回都记录下来，然后对比不同模型的实际返回结构，在业务代码里抽一层通用的解析函数，专门处理可能出现的差异。另外，在配置里尽量使用各厂商最通用的参数，少用冷门的专属参数，能减少很多兼容性问题。

4.4 成本统计不准的问题

成本统计是litellm一个很吸引人的功能，它在日志里记录每次请求的token数和费用估算。不过这里有个需要注意的地方：它的费用是根据模型名匹配官方定价表算出来的，如果某个模型没有收录到它的定价表里，费用就会显示为0或者按默认价格算，统计出来就失真了。

使用成本统计功能之前，最好先核对一下你用的模型是否在支持的列表里。不再支持的情况下，可以自己在配置里补充模型的价格信息。我自己是在月底对账的时候发现费用差异比较大，排查下来才发现是这个问题。

列出几个我在实际使用中遇到的常见问题和排查方向：

4.5 给刚上手的人几条配置建议

最后再给刚开始用这个工具的朋友几个建议。第一个建议是，千万别一上来就把所有模型都接进去。选两个最常用的先跑通，一个做主力，一个做fallback，其他的后面再加。第二个建议是，把日志功能从一开始就打开，用的时候多看一眼请求记录，能少踩很多排查的坑。第三个建议是，代理服务部署之后，给团队的虚拟Key设好预算上限，避免有人一次实验就把量跑超了。

4.6 一个具体场景：给代理加预算控制

我再说得细一点，预算控制这块是我觉得真正值得花时间研究的。litellm代理服务支持为每个虚拟Key设置额度，比如某位同学的Key只能用20美元，用完了就自动拒绝请求。

这个功能的实际价值在于防止失控。我曾经在一个项目里，大家共用一个密钥，有人跑了一晚上批量实验，结果账单上来的时候所有人都愣住了。后来我配置了虚拟Key的预算限制，把每个人的用量都圈住，问题再也没出现过。

配置方式是在代理后台生成虚拟Key时，直接指定预算金额。团队里每个人用自己的独立Key，谁用了多少一目了然，对账也方便。这个机制对多人协作场景帮助极大。

5. 我的一点实际体会

用了一圈下来，我的感受是：litellm确实把模型接入这个原本很琐碎的事情，简化到了可维护的层面。它最大的价值不是帮你省掉那几十行请求代码，而是把模型切换、密钥管理、成本控制、故障转移这些基础设施性质的事情集中到一处。对于还在用自己写的封装工具、并且模型接入数量超过两个的团队，我建议尽早评估一下换到统一网关方案。

如果要从零开始搭一套，路径其实很清晰：先装依赖，用SDK模式把请求链路跑通，再起代理服务，然后逐步把模型配置、虚拟Key、预算、日志这些完善起来。不用一口气做得很完美，先把基础链路跑顺，后续再慢慢加强。

最后分享一个小经验，如果遇到排查起来很费劲的问题，第一时间不是去看代码，而是去看代理服务的日志。litellm的日志里会输出每次请求走的路由、耗时和报错详情，大多数问题在日志里都能找到答案。先看日志，再改配置，最后才改代码，这是我排障效率最高的顺序。