1. 项目缘起从“API孤岛”到统一编程助手的构想作为一名长期在代码和命令行之间穿梭的开发者我最近被一个痛点反复折磨手头有好几个不同厂商的AI编程助手比如OpenAI的Codex、Anthropic的Claude Code还有Azure上的各种模型。它们各有千秋有的长于代码补全有的精于代码解释但每次想用哪个就得去翻对应的API文档切换不同的环境变量或者打开不同的客户端工具。这感觉就像车库里停了好几辆好车但每辆车的钥匙都不同想开哪辆还得先找半天钥匙效率大打折扣。更具体地说我常用的场景是在终端里写脚本、调试或者快速原型验证时希望能像调用ls、grep一样用一个简单的命令就能让AI帮我生成代码片段、解释一段复杂的逻辑甚至重构函数。但现实是为了用上Claude Code我得配置一套东西想切回Codex又得换另一套。这种割裂感严重打断了我的“心流”。直到我遇到了LiteLLM。这个工具的名字就很有意思“轻量级LLM”。它的核心目标正是解决我遇到的这个问题提供一个统一的接口来调用市面上几乎所有的主流大语言模型LLM。你可以把它想象成一个“万能适配器”或者“模型路由层”。无论后端是OpenAI、Anthropic、Azure OpenAI、Google Gemini还是Cohere、Hugging Face你只需要通过LiteLLM这一套API格式去调用它帮你处理所有与不同厂商API通信的细节。那么结合标题“用 LiteLLM 打通 Codex CLI 与 Claude Code”这个项目的核心构想就清晰了利用LiteLLM作为桥梁构建一个统一的命令行工具CLI。这个CLI允许我使用相同的命令语法随时切换或指定使用后端的Codex或任何OpenAI兼容模型还是Claude Code来执行编程任务真正实现“有key即可编程自由”。这意味着我只需要管理好我的API密钥就能在终端里无缝调用最合适的AI模型来辅助编码彻底告别切换工具的繁琐。2. LiteLLM核心机制解析它如何成为“万能适配器”在动手搭建我们的CLI工具之前有必要深入理解一下LiteLLM的工作原理。这不仅能帮助我们更好地使用它也能在出现问题时快速定位。LiteLLM并非魔法它的优雅源于清晰的设计模式。2.1 统一的请求与响应格式LiteLLM的核心抽象是它定义了一套与OpenAI API高度兼容的通用格式。这意味着无论你想调用哪个模型你发送的请求体结构基本是一致的。一个最基础的完成Completion请求看起来是这样的response completion( modelgpt-3.5-turbo, # 或 claude-3-opus-20240229 messages[ {role: user, content: 用Python写一个快速排序函数} ] )关键在于model这个参数。在LiteLLM的语境下model字符串是一个“路由指令”。它不仅仅是一个模型名更包含了LiteLLM应该如何路由这个请求的信息。LiteLLM的模型参数路由逻辑LiteLLM通过解析我们传入的model字符串来决定将请求发送到哪里。其内部维护了一个庞大的模型名称映射表。例如当你传入modelgpt-3.5-turboLiteLLM会识别出这是OpenAI的模型于是使用你配置的OPENAI_API_KEY按照OpenAI的API端点格式发送请求。当你传入modelclaude-3-opus-20240229LiteLLM会识别出这是Anthropic的模型转而使用你配置的ANTHROPIC_API_KEY并按照Anthropic的API格式注意Anthropic的原始API格式与OpenAI不同来构造和发送请求。对于Azure OpenAI模型名可能类似modelazure/gpt-35-turboLiteLLM会根据azure/前缀去读取AZURE_API_BASE,AZURE_API_VERSION等环境变量构造符合Azure OpenAI REST API规范的请求。这个过程对使用者是完全透明的。我们只需要以OpenAI的方式写代码LiteLLM负责完成到目标API的“转译”工作。这大大降低了多模型开发的复杂度。2.2 环境变量管理与密钥安全LiteLLM通常通过环境变量来读取各平台的API密钥和配置这是管理敏感信息的标准且安全的方式。对于我们的项目至少需要配置以下环境变量# OpenAI (包括Codex 如果你有访问权限) export OPENAI_API_KEYsk-... # Anthropic (Claude Code) export ANTHROPIC_API_KEYsk-ant-... # Azure OpenAI (如果需要) export AZURE_API_BASEhttps://your-resource.openai.azure.com/ export AZURE_API_VERSION2024-02-15-preview export AZURE_API_KEY...重要提示永远不要将API密钥硬编码在脚本或代码中尤其是打算分享的代码。环境变量或安全的密钥管理服务如AWS Secrets Manager, HashiCorp Vault是唯一推荐的方式。在.bashrc、.zshrc或使用dotenv文件加载是常见的本地开发实践。2.3 错误处理与重试机制在实际使用中网络波动、API限流、模型过载都是常见问题。一个健壮的CLI工具必须能妥善处理这些异常。LiteLLM内置了一些实用的功能自动重试对于可重试的错误如429请求过多、5xx服务器错误LiteLLM可以配置自动重试逻辑避免因临时故障导致任务失败。统一的错误格式尽管底层API返回的错误信息千差万别LiteLLM会尝试将其规范化为统一的异常类型方便我们在代码里进行捕获和处理。例如可以统一捕获litellm.exceptions.APIConnectionError或litellm.exceptions.RateLimitError。Fallback策略这是一个高级但非常有用的特性。你可以为请求指定一个模型列表如model[gpt-4, gpt-3.5-turbo]并设置fallbacksTrue。当主模型gpt-4因任何原因失败时LiteLLM会自动尝试使用列表中的下一个模型gpt-3.5-turbo来完成任务保证了服务的可用性。理解这些机制后我们就能明白基于LiteLLM构建CLI我们获得的不是一个简单的API封装而是一个具备生产级鲁棒性的模型调用中间层。3. 构建统一编程助手CLI从设计到实现有了LiteLLM作为基石我们现在可以开始设计和实现我们的命令行工具了。我们的目标是创建一个名为aicode或其他你喜欢的名字的命令它至少支持以下功能通过命令行参数或交互式选择指定使用哪个模型如codexclaude。接受用户输入的提示Prompt该提示可以来自标准输入、文件或直接的命令行参数。调用指定的模型生成代码或文本。将结果清晰、格式化地输出到终端或根据选项保存到文件。3.1 项目初始化与依赖管理首先我们创建一个新的Python项目目录。使用虚拟环境是Python开发的最佳实践它能隔离项目依赖。mkdir ai-code-cli cd ai-code-cli python -m venv venv # 创建虚拟环境 # 激活虚拟环境 # 在Linux/macOS上 source venv/bin/activate # 在Windows上 # venv\Scripts\activate # 安装核心依赖 pip install litellm1.0.0 # 安装用于构建友好CLI的库推荐typer或click这里使用typer它更现代且基于类型提示。 pip install typer[all] # 可选用于丰富终端输出如颜色、进度条 pip install rich接下来创建项目的基本结构ai-code-cli/ ├── venv/ # 虚拟环境目录.gitignore中应忽略 ├── src/ │ └── aicode/ │ ├── __init__.py │ ├── __main__.py # 使得可以通过 python -m aicode 运行 │ ├── cli.py # Typer应用主入口 │ ├── core.py # 核心业务逻辑调用LiteLLM │ └── config.py # 配置管理如模型别名映射 ├── .env.example # 环境变量示例文件 ├── requirements.txt └── README.md使用pip freeze requirements.txt生成依赖列表。3.2 核心调用逻辑封装在src/aicode/core.py中我们将封装与LiteLLM交互的核心函数。这里的关键是处理模型别名并为用户提供一个简单的接口。import os import litellm from litellm import completion from typing import Optional, Dict, Any import logging # 配置日志便于调试 logging.basicConfig(levellogging.WARNING) litellm.set_verbose False # 关闭LiteLLM的详细日志除非需要调试 # 模型别名映射字典 # 用户可以使用简短的别名如 codex, claude 我们在内部将其映射到LiteLLM识别的标准模型名。 MODEL_ALIASES { # OpenAI 系列 codex: code-davinci-002, # 注意Codex模型可能已不再对新用户开放可用gpt-3.5-turbo-instruct或gpt-4替代 gpt4: gpt-4, gpt4-turbo: gpt-4-turbo-preview, gpt3: gpt-3.5-turbo, # Anthropic 系列 (Claude) claude: claude-3-opus-20240229, # 最强版 claude-sonnet: claude-3-sonnet-20240229, # 均衡版 claude-haiku: claude-3-haiku-20240307, # 快速版 # Azure OpenAI 系列 (需要配置对应环境变量) azure-gpt4: azure/gpt-4, azure-gpt35: azure/gpt-35-turbo, } def get_model_name(alias: str) - str: 根据用户提供的别名获取真实的LiteLLM模型名。 # 如果别名已经在映射表中返回映射值 if alias in MODEL_ALIASES: return MODEL_ALIASES[alias] # 否则假定用户直接输入了LiteLLM支持的模型名如 gpt-3.5-turbo return alias def generate_code( prompt: str, model_alias: str claude, # 默认使用Claude temperature: float 0.2, # 较低的温度使输出更确定适合代码生成 max_tokens: int 1500, stream: bool False, # 是否流式输出 **kwargs ) - str: 调用LiteLLM生成代码或文本。 Args: prompt: 用户输入的提示词。 model_alias: 模型别名或直接模型名。 temperature: 生成随机性0-1之间越低越确定。 max_tokens: 生成的最大token数。 stream: 是否启用流式响应。 **kwargs: 其他传递给litellm.completion的参数。 Returns: 模型生成的文本内容。 model get_model_name(model_alias) messages [{role: user, content: prompt}] try: response completion( modelmodel, messagesmessages, temperaturetemperature, max_tokensmax_tokens, streamstream, **kwargs ) if stream: # 处理流式响应逐块打印并收集 collected_chunks [] full_content print(\n--- 开始流式生成 ---) for chunk in response: if chunk.choices[0].delta.content is not None: content chunk.choices[0].delta.content print(content, end, flushTrue) full_content content collected_chunks.append(chunk) print(\n--- 生成结束 ---) return full_content else: # 非流式响应直接返回内容 content response.choices[0].message.content return content except Exception as e: # 这里可以更精细地捕获litellm或网络异常 logging.error(f调用模型 {model} 时发生错误: {e}) # 返回一个友好的错误信息或根据错误类型进行fallback处理 return f[错误] 无法从模型 {model_alias} 获取响应。错误信息: {str(e)}这个core.py文件完成了最核心的模型调用封装。我们定义了模型别名映射让用户可以用更简短易记的名字。generate_code函数处理了流式和非流式两种响应方式并进行了基本的异常捕获。3.3 使用Typer构建命令行界面接下来在src/aicode/cli.py中我们使用Typer来构建用户直接交互的CLI。import typer from typing import Optional from pathlib import Path import sys from .core import generate_code, MODEL_ALIASES from rich.console import Console from rich.syntax import Syntax from rich.panel import Panel import pyperclip # 可选用于复制到剪贴板 app typer.Typer(help 你的统一AI编程助手CLI通过LiteLLM调用多种大模型。) console Console() app.command() def ask( prompt: str typer.Argument(None, help直接输入的提示词。如果未提供将从标准输入读取。), model: str typer.Option(claude, --model, -m, helpf指定使用的模型。可用别名: {, .join(MODEL_ALIASES.keys())}。也可直接使用LiteLLM支持的模型名。), temperature: float typer.Option(0.2, --temp, -t, help生成温度 (0.0-2.0)。值越低输出越确定越高越有创造性。), max_tokens: int typer.Option(1500, --tokens, -n, help生成的最大token数量。), file: Optional[Path] typer.Option(None, --file, -f, help从文件中读取提示词。), stream: bool typer.Option(False, --stream, -s, help启用流式输出实时看到生成过程。), copy: bool typer.Option(False, --copy, -c, help将输出结果复制到系统剪贴板。), output: Optional[Path] typer.Option(None, --output, -o, help将输出保存到指定文件。), ): 向AI模型提问并获取代码或文本回答。 # 1. 获取提示词 final_prompt if file: if not file.exists(): console.print(f[bold red]错误: 文件 {file} 不存在。[/bold red]) raise typer.Exit(code1) final_prompt file.read_text(encodingutf-8) console.print(f[dim]从文件 [bold]{file}[/bold] 读取提示词...[/dim]) elif prompt: final_prompt prompt else: # 从标准输入读取支持管道 console.print([dim]从标准输入读取提示词... (CtrlD结束输入)[/dim]) final_prompt sys.stdin.read().strip() if not final_prompt: console.print([bold red]错误: 未提供提示词。请通过参数、文件或标准输入提供。[/bold red]) raise typer.Exit(code1) # 2. 显示即将执行的操作 console.print(Panel.fit( f[bold cyan]模型:[/bold cyan] {model}\n f[bold cyan]提示词长度:[/bold cyan] {len(final_prompt)} 字符\n f[bold cyan]温度:[/bold cyan] {temperature}\n f[bold cyan]流式模式:[/bold cyan] {开启 if stream else 关闭}, title 请求参数, border_stylecyan )) # 3. 调用核心函数生成内容 console.print([dim]正在调用模型请稍候...[/dim]) generated_text generate_code( promptfinal_prompt, model_aliasmodel, temperaturetemperature, max_tokensmax_tokens, streamstream, ) # 4. 处理并输出结果 if not stream: # 非流式模式下在这里统一输出 # 尝试将输出识别为代码并进行语法高亮 # 这里简单判断如果包含常见代码块标记或缩进规律则按代码处理 # 更复杂的可以用 language-detection 库 language None if in generated_text or def in generated_text or function in generated_text or import in generated_text: language python # 简单假设可增强逻辑 # 清理可能的markdown代码块标记 if generated_text.startswith() and generated_text.endswith(): lines generated_text.split(\n) if lines[0].startswith(): language lines[0][3:] or language generated_text \n.join(lines[1:-1]) if language: syntax Syntax(generated_text, language, thememonokai, line_numbersTrue) console.print(Panel(syntax, title✨ 生成的代码, border_stylegreen)) else: console.print(Panel(generated_text, title✨ 生成的文本, border_styleblue)) # 5. 后处理复制到剪贴板或保存到文件 if copy: try: pyperclip.copy(generated_text) console.print([green]✓ 输出已复制到剪贴板。[/green]) except Exception as e: console.print(f[yellow]⚠ 无法复制到剪贴板: {e}[/yellow]) if output: output.write_text(generated_text, encodingutf-8) console.print(f[green]✓ 输出已保存到文件: [bold]{output}[/bold][/green]) app.command(namelist-models) def list_models(): 列出所有预定义的模型别名及其对应的真实模型。 console.print([bold underline]可用的模型别名:[/bold underline]) for alias, real_model in MODEL_ALIASES.items(): console.print(f [cyan]{alias:20}[/cyan] - [yellow]{real_model}[/yellow]) console.print(\n[dim]你也可以直接使用任何LiteLLM支持的模型名如 gpt-4。[/dim]) app.command() def config(): 显示当前配置的环境变量隐藏密钥值。 import os console.print([bold underline]当前相关环境变量:[/bold underline]) relevant_vars [OPENAI_API_KEY, ANTHROPIC_API_KEY, AZURE_API_BASE, AZURE_API_KEY] for var in relevant_vars: value os.getenv(var) if value: # 只显示前4位和后4位保护密钥 masked value[:4] * * (len(value)-8) value[-4:] if len(value) 8 else *** console.print(f [green]{var}:[/green] {masked}) else: console.print(f [red]{var}:[/red] 未设置) if __name__ __main__: app()在src/aicode/__main__.py中我们只需简单导入from .cli import app if __name__ __main__: app()3.4 安装与使用你的CLI工具为了使aicode命令能在终端任何地方运行我们需要以“可编辑”模式安装这个包。在项目根目录ai-code-cli/下创建一个简单的setup.py或使用pyproject.toml。这里使用pyproject.toml现代方式[build-system] requires [setuptools61.0] build-backend setuptools.build_meta [project] name ai-code-cli version 0.1.0 description A unified CLI for AI coding assistants via LiteLLM readme README.md requires-python 3.8 dependencies [ litellm1.0.0, typer[all]0.9.0, rich13.0, pyperclip1.8.2, # 可选 ] [project.scripts] aicode aicode.cli:app然后在项目根目录下执行安装pip install -e .现在aicode命令就全局可用了让我们测试一下# 1. 列出支持的模型 aicode list-models # 2. 使用Claude默认生成一个Python函数 aicode ask 写一个Python函数计算斐波那契数列的第n项 # 3. 使用Codex或GPT模型并启用流式输出 aicode ask -m codex -s 用JavaScript实现一个深拷贝函数 # 4. 从文件读取提示词并保存结果 echo 解释下面这段SQL查询的作用 SELECT * FROM users WHERE active 1 JOIN orders ON users.id orders.user_id; prompt.txt aicode ask -f prompt.txt -m claude-sonnet -o explanation.md # 5. 通过管道传递输入 cat my_problem.txt | aicode ask -m gpt4至此一个功能完整、用户友好的统一AI编程助手CLI就搭建完成了。它充分利用了LiteLLM的模型路由能力让你在终端里用一条命令就能调动不同的AI大脑。4. 高级技巧与实战避坑指南工具搭建好了但要让它真正融入你的工作流成为得心应手的“副驾驶”还需要一些实战经验和技巧。下面分享我在使用和扩展这个CLI过程中积累的一些心得和踩过的坑。4.1 模型选择策略与成本权衡不同的模型在能力、速度和成本上差异巨大。我们的CLI赋予了自由选择的权利但也带来了选择的负担。以下是我的经验之谈追求极致代码质量与逻辑复杂度时优先选择claude-3-opus或gpt-4。它们在解决复杂算法问题、理解模糊需求、生成架构清晰的代码方面表现最佳。尤其是Claude Opus在长上下文和代码推理上给我的印象非常深刻。但它们的缺点是速度慢、价格贵。适合用于关键模块的设计和评审。日常快速辅助与补全claude-3-sonnet和gpt-3.5-turbo是绝佳的平衡之选。Sonnet的速度比Opus快得多成本低一个数量级而能力对于大多数日常编码任务如写工具函数、解析数据、生成简单脚本已经绰绰有余。GPT-3.5-Turbo同理且API稳定性极高。超轻量级任务与探索claude-3-haiku是目前速度最快的模型之一成本极低。它非常适合用于代码解释快速理解一段陌生代码。语法转换将Python代码改成JavaScript。简单查询“这个Linux命令是什么意思”头脑风暴快速生成几个函数名或变量名选项。 对于这些任务用Opus或GPT-4无异于“大炮打蚊子”Haiku完全够用且响应飞快。成本监控提醒自由切换模型的代价是可能产生意想不到的API费用。务必在云服务商后台设置用量告警和预算限制。一个实用的技巧是在CLI中集成一个简单的成本估算功能根据模型单价和输入输出token数粗略计算或者在非关键任务中主动选择更便宜的模型。4.2 提示词Prompt工程优化CLI只是渠道提示词才是你与AI沟通的语言。同样的模型不同的提示词效果天差地别。角色设定Role Playing在提示词开头明确AI的角色能极大提升输出质量。例如你是一位经验丰富的Python后端开发专家擅长编写高效、可读且符合PEP 8规范的代码。请完成以下任务...这比直接说“写一个Python函数”要有效得多。提供上下文与约束AI不是巫师它需要信息。如果你在修改一个已有文件最好的方式是用-f参数将整个文件或相关片段喂给它并在提示词中明确指出“以下是utils.py文件的内容请在其中添加一个名为validate_email的函数...”。同时给出明确的约束“函数必须使用正则表达式验证并抛出ValueError异常。”迭代式交互不要期望一次提示就得到完美答案。我们的CLI适合快速迭代。例如aicode ask -m claude 用Pandas写一个数据清洗函数- 得到初版。发现初版没有处理空值接着问aicode ask -m claude 很好但请为这个函数增加处理NaN值的逻辑用中位数填充数值列用‘Unknown’填充字符串列。这种“对话”模式比试图在一个超长的提示词里列出所有要求要高效。使用“思维链”Chain-of-Thought对于复杂问题要求AI“逐步思考”。例如“我们要解析这个复杂的日志文件。请先列出你认为关键的数据提取步骤然后根据这些步骤编写Python代码。”这能引导模型进行更结构化的推理减少“一本正经胡说八道”的几率。4.3 常见错误排查与LiteLLM调试即使有了LiteLLM这层抽象网络、配置和API本身的问题依然存在。这里有几个排查思路“Model not supported” 错误检查模型名首先用aicode list-models确认你用的别名是否正确。如果直接使用模型名去LiteLLM的官方文档查看其支持的完整模型列表。模型名更新很快旧名称可能已失效。检查API密钥权限你是否拥有访问该模型的权限例如code-davinci-002Codex已对大多数新用户关闭。gpt-4的API访问可能需要单独申请。确保你的API密钥对应的账户有权使用目标模型。超时或网络错误设置超时参数在调用completion时可以传递timeout参数单位秒。LiteLLM默认可能有超时设置但对于慢模型如Opus可以适当延长。response completion(model..., messages..., timeout120) # 等待120秒启用重试LiteLLM有内置重试但你可以通过环境变量控制export LITELLM_NUM_RETRIES3。流式输出中断或不完整流式输出对网络稳定性要求较高。如果频繁中断可以考虑关闭流式-s一次性获取完整结果。检查你的终端或IDE是否对输出流做了缓冲有时这会导致显示延迟或混乱。启用详细日志当遇到摸不着头脑的错误时在代码中或通过环境变量打开LiteLLM的详细日志是终极调试手段。import litellm litellm.set_verbose True或者在调用CLI前设置环境变量export LITELLM_LOGDEBUG。这会打印出详细的HTTP请求和响应信息帮你看清到底是请求格式错了还是API返回了错误。4.4 CLI功能扩展思路基础版本已经可用但你可以根据个人习惯将其打造成专属神器会话Session模式目前的每次调用都是独立的。可以实现一个简单的会话上下文让AI记住之前的对话。这可以通过在本地临时文件中保存对话历史来实现下次调用时自动将历史作为上下文传入。代码直接执行与验证一个大胆的想法是让CLI不仅能生成代码还能在安全沙箱如Docker容器中自动运行生成的代码来验证其正确性。这需要极其谨慎地处理安全问题仅限于运行可信的、简单的代码片段。与编辑器集成虽然我们在终端使用但可以通过生成代码片段文件或者与编辑器如VSCode的快捷键绑定实现更流畅的体验。例如在编辑器中选中一段代码按个快捷键就能调用CLI进行解释或重构并将结果直接插入编辑器。预设提示词模板将常用的提示词保存为模板。例如aicode refactor -f myfile.py可以自动应用一个“代码重构”模板来生成提示词省去重复输入。通过LiteLLM打通各个AI编程助手构建统一CLI的过程本质上是一次对开发者工作流的深度优化。它削减了不必要的工具切换成本让你能更专注于问题本身而非与工具的搏斗。这个项目没有终点你可以根据自己的需求不断打磨和扩展它使其真正成为你编码过程中如臂使指的一部分。