在实际项目开发中无论是构建智能客服、内容生成工具还是数据分析助手调用大语言模型LLM的 API 已成为标准操作。然而开发者面临的挑战远不止于简单的接口调用。从 API Key 的获取与管理、不同模型参数的适配到处理复杂的错误码如 400、429、529和上下文长度限制每一步都可能成为项目落地的障碍。特别是当模型版本更新、价格策略调整或出现新的高效推理方案时如何快速、稳定、低成本地集成这些能力是每个技术团队必须解决的问题。本文将以一个资深开发者的视角系统性地梳理大模型 API 集成的全流程。我们将从核心概念与工作机制讲起然后逐步完成环境准备、依赖配置、代码实现与运行验证。更重要的是文章将深入探讨那些官方文档可能一笔带过但在实际生产中频繁出现的错误及其排查路径例如400 type must be in [enabled, disabled, auto]、400 this models maximum context length is...、529 overloaded等。无论你是初次接触 LLM API 的开发者还是正在为生产环境中的稳定性问题寻找解决方案本文都将提供一套可复现、可排查的实践指南。1. 理解大模型 API 的核心概念与工作机制在编写第一行代码之前理解大模型 API 的基本构成和工作原理至关重要。这能帮助你在遇到问题时快速定位是网络、鉴权、参数还是服务端的问题。1.1 什么是大模型 API大模型 API 本质上是一个远程过程调用RPC接口它允许你将一段文本称为“提示”或“Prompt”发送到服务提供商的服务器。服务器上的大型语言模型对这段文本进行处理、推理并生成一段新的文本称为“补全”或“Completion”返回给你。整个过程与你调用一个本地函数类似但计算发生在远端。目前主流的大模型 API 提供商包括 OpenAI (ChatGPT)、 Anthropic (Claude)、 Google (Gemini)、 国内如智谱AI (GLM)、 百度文心、 阿里通义千问、 DeepSeek、 Kimi 等。它们都提供了类似的基于 HTTP 的 RESTful API 或 WebSocket 接口。1.2 API 调用的关键组件一次完整的 API 调用通常包含以下几个核心部分端点 (Endpoint): API 服务的 URL。例如OpenAI 的聊天补全端点是https://api.openai.com/v1/chat/completions。认证 (Authentication): 几乎所有的商业 API 都需要认证通常通过在 HTTP 请求头中携带一个密钥API Key来实现例如Authorization: Bearer sk-...。请求体 (Request Body): 一个 JSON 对象包含了调用的所有参数。最重要的参数包括model: 指定使用哪个模型如gpt-4o,claude-3-5-sonnet,deepseek-v4-pro。messages: 一个消息对象数组定义了对话的上下文。通常包含role(如system,user,assistant) 和content。max_tokens: 限制模型生成的最大令牌数。temperature: 控制生成文本的随机性创造性。响应体 (Response Body): 同样是一个 JSON 对象包含了模型生成的结果、使用的令牌数等信息。核心字段是choices[0].message.content。1.3 常见计费与性能概念令牌 (Token): 文本被切分后的基本单位。对于英文大约 1个token对应0.75个单词中文更复杂一个字可能对应1-2个token。API 调用通常按输入和输出合计的令牌数计费。上下文长度 (Context Length): 模型单次调用能够处理的最大令牌数包括输入和输出。这是一个硬性限制如果超出会报错例如400 this models maximum context length is 1048565 tokens。推理效率: 指模型处理请求并返回结果的速度和资源消耗。更高的效率意味着更低的延迟和成本。模型提供商通过优化模型架构如混合专家模型 MoE、推理引擎和硬件来提升效率。API 降价: 当模型推理效率提升、硬件成本下降或市场竞争加剧时提供商可能会降低每百万令牌的调用费用这对于高频使用的应用是重大利好。理解了这些你就知道为什么配置model参数、计算上下文长度和管理 API Key 如此重要了。2. 环境准备与依赖配置开始编码前我们需要一个干净的开发环境。本文将使用 Python 作为示例语言因为它拥有最丰富的大模型 API 客户端库。2.1 基础环境要求确保你的开发机满足以下条件组件要求说明操作系统Windows 10/11, macOS, Linux无特殊要求推荐 Linux/macOS 用于生产部署。Python3.8 或更高版本使用python --version检查。包管理工具pip通常随 Python 安装。网络可访问目标 API 服务对于国内模型网络通常无障碍对于海外模型需确保网络连通性。代码编辑器VS Code, PyCharm 等任选。2.2 创建虚拟环境与安装依赖使用虚拟环境可以隔离项目依赖避免版本冲突。# 1. 创建项目目录并进入 mkdir llm-api-integration cd llm-api-integration # 2. 创建 Python 虚拟环境 (以 venv 为例) python -m venv venv # 3. 激活虚拟环境 # Windows (PowerShell) .\venv\Scripts\Activate.ps1 # Linux/macOS source venv/bin/activate # 4. 升级 pip pip install --upgrade pip # 5. 安装核心依赖 # openai 库是调用 OpenAI 及 OpenAI 兼容 API如许多国内模型和开源模型的事实标准。 pip install openai # requests 库用于更底层的 HTTP 调用方便我们理解原理和自定义。 pip install requests # python-dotenv 用于管理环境变量安全地存储 API Key。 pip install python-dotenv安装完成后你的虚拟环境中应该有了必要的工具库。2.3 获取并安全存储 API KeyAPI Key 是你的付费凭证必须妥善保管绝不能直接硬编码在代码中或提交到版本控制系统如 Git。获取 API Key:OpenAI: 登录 OpenAI Platform 创建新的 API Key。国内模型如智谱、DeepSeek: 访问对应平台的开放平台官网注册账号并申请 API Key。其他平台流程类似。使用环境变量管理: 在项目根目录创建一个名为.env的文件注意前面的点。# .env 文件内容示例 OPENAI_API_KEYsk-your-openai-key-here DEEPSEEK_API_KEYyour-deepseek-key-here ZHIPU_API_KEYyour-zhipu-key-here # 可以继续添加其他模型的 KEY注意请务必将.env添加到你的.gitignore文件中确保它不会被意外提交。在代码中加载环境变量: 我们将使用python-dotenv在程序启动时加载这些变量。3. 实现基础 API 调用从最简单的请求开始现在我们来实现一个最基础的、面向 OpenAI 格式兼容 API 的调用。我们将创建一个basic_demo.py文件。3.1 编写最小化调用代码# basic_demo.py import os from openai import OpenAI from dotenv import load_dotenv # 1. 加载 .env 文件中的环境变量 load_dotenv() # 2. 初始化客户端 # 默认会读取环境变量中的 OPENAI_API_KEY 和 OPENAI_BASE_URL # 对于 OpenAIbase_url 默认是 https://api.openai.com/v1 client OpenAI( api_keyos.getenv(OPENAI_API_KEY), # 显式指定更清晰 # base_urlhttps://api.openai.com/v1, # 如果是 OpenAI可以省略 ) # 3. 发起聊天补全请求 try: response client.chat.completions.create( modelgpt-3.5-turbo, # 指定模型这里用一个较便宜的模型做测试 messages[ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 请用一句话介绍你自己。} ], max_tokens100, # 限制生成长度 temperature0.7, # 控制创造性 ) # 4. 提取并打印结果 answer response.choices[0].message.content print(f助手回复: {answer}) # 5. 打印本次调用的令牌使用情况用于成本估算 usage response.usage print(f令牌使用 - 提示: {usage.prompt_tokens}, 补全: {usage.completion_tokens}, 总计: {usage.total_tokens}) except Exception as e: print(f调用 API 时发生错误: {e})关键点解释:load_dotenv(): 自动从项目根目录的.env文件加载变量到os.environ。OpenAI(): 这是openai库的官方客户端。即使你调用的是非 OpenAI 但兼容其 API 格式的服务如许多开源模型部署也可以使用这个客户端只需修改base_url和api_key。client.chat.completions.create(): 这是发起聊天请求的核心方法。参数messages的格式是对话历史列表模型会根据整个列表的上下文来生成回复。temperature: 值范围 0~2。值越低输出越确定、保守值越高输出越随机、有创造性。对于事实性问答建议 0.1~0.3对于创意写作可以 0.7~1.0。3.2 运行与验证在终端中确保虚拟环境已激活然后运行脚本python basic_demo.py如果一切正常你将看到类似以下的输出助手回复: 你好我是一个由OpenAI训练的人工智能助手致力于为你提供信息解答、问题帮助和各种支持服务。 令牌使用 - 提示: 27, 补全: 30, 总计: 57这证明你的 API Key、网络和基础代码都是可用的。如果出现错误请跳到第 6 章进行排查。4. 适配不同模型提供商与处理复杂参数实际项目中你可能需要调用多个不同提供商的模型。它们的 API 端点、参数命名可能略有不同。openai库的客户端通过base_url参数提供了很好的兼容性。4.1 调用 DeepSeek API假设你已获取 DeepSeek 的 API Key 并存入.env文件的DEEPSEEK_API_KEY。DeepSeek 的 API 与 OpenAI 格式兼容。# deepseek_demo.py import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() # 初始化指向 DeepSeek API 的客户端 client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com, # DeepSeek 的 API 基础地址 ) try: response client.chat.completions.create( modeldeepseek-chat, # 使用 DeepSeek 的模型名称 messages[ {role: user, content: 什么是机器学习} ], max_tokens200, streamFalse, # 非流式输出 ) print(fDeepSeek 回复: {response.choices[0].message.content}) except Exception as e: print(f调用 DeepSeek API 失败: {e})注意模型名称不同的提供商有不同的模型标识符。你必须使用提供商文档中指定的正确模型名。例如DeepSeek 可能是deepseek-chat或deepseek-v4-pro而错误使用gpt-3.5-turbo会导致400 the supported api model names are...错误。4.2 处理流式输出 (Streaming)对于生成长文本的场景流式输出可以提升用户体验让用户看到逐步生成的过程而不是等待全部生成完毕。# streaming_demo.py import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) try: # 设置 streamTrue stream client.chat.completions.create( modelgpt-3.5-turbo, messages[{role: user, content: 写一首关于春天的五言绝句。}], max_tokens50, streamTrue, # 启用流式输出 temperature0.8, ) print(开始流式接收) collected_chunks [] for chunk in stream: if chunk.choices[0].delta.content is not None: content chunk.choices[0].delta.content print(content, end, flushTrue) # 逐块打印不换行 collected_chunks.append(content) print() # 最后换行 full_reply .join(collected_chunks) # print(f\n完整回复: {full_reply}) except Exception as e: print(f\n流式调用出错: {e})流式响应中每个chunk包含生成文本的一小部分 (delta.content)。你需要将这些片段拼接起来才能得到完整回复。4.3 使用 Function Calling / Tool Calls许多模型支持函数调用OpenAI或工具调用Claude这允许模型在对话中决定调用你预先定义好的函数并将结果返回给模型从而实现更复杂的功能如查询天气、执行计算。以下是一个模拟天气查询的简化示例# tool_calls_demo.py import os import json from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) # 1. 定义工具函数列表 tools [ { type: function, function: { name: get_current_weather, description: 获取指定城市的当前天气, parameters: { type: object, properties: { location: { type: string, description: 城市名例如北京San Francisco, }, unit: {type: string, enum: [celsius, fahrenheit]}, }, required: [location], }, }, } ] # 2. 模拟一个天气查询函数 def get_current_weather(location, unitcelsius): 模拟天气查询实际项目中应调用真实天气API print(f[模拟函数调用] 查询地点: {location}, 单位: {unit}) # 返回模拟数据 return json.dumps({location: location, temperature: 22, unit: unit, forecast: [晴朗, 微风]}) try: # 3. 第一次调用模型可能会决定调用工具 response client.chat.completions.create( modelgpt-3.5-turbo, messages[{role: user, content: 北京现在天气怎么样}], toolstools, tool_choiceauto, # 让模型自动决定是否调用工具 ) response_message response.choices[0].message tool_calls response_message.tool_calls # 4. 检查模型是否要求调用工具 if tool_calls: print(模型请求调用工具。) available_functions { get_current_weather: get_current_weather, } # 将模型的回复添加到消息历史中 messages [{role: user, content: 北京现在天气怎么样}] messages.append(response_message) # 包含工具调用请求的回复 # 5. 执行每个被请求的工具调用 for tool_call in tool_calls: function_name tool_call.function.name function_to_call available_functions[function_name] function_args json.loads(tool_call.function.arguments) # 执行函数 function_response function_to_call( locationfunction_args.get(location), unitfunction_args.get(unit, celsius), ) # 将函数执行结果作为新的消息追加 messages.append( { role: tool, tool_call_id: tool_call.id, content: function_response, } ) # 6. 第二次调用将函数执行结果返回给模型让它生成面向用户的回答 second_response client.chat.completions.create( modelgpt-3.5-turbo, messagesmessages, ) print(f最终回复: {second_response.choices[0].message.content}) else: # 模型没有调用工具直接回复 print(f模型直接回复: {response_message.content}) except Exception as e: print(f工具调用过程出错: {e})这个流程展示了模型如何与你定义的工具进行交互是实现复杂 AI 应用如智能体的基础。5. 生产环境关键配置与最佳实践学习环境能跑通只是第一步。将 LLM API 集成到生产环境需要考虑稳定性、成本、监控和错误处理。5.1 配置管理外置化永远不要将 API Key、模型端点等配置硬编码。除了使用.env文件在生产环境中更推荐使用配置中心如 Apollo, Nacos或云服务商提供的密钥管理服务如 AWS Secrets Manager, Azure Key Vault。# config_manager.py (示例结构) import os from abc import ABC, abstractmethod from typing import Dict, Any class ConfigProvider(ABC): abstractmethod def get(self, key: str, defaultNone) - Any: pass class EnvConfigProvider(ConfigProvider): 从环境变量读取配置用于开发和测试 def get(self, key: str, defaultNone) - Any: return os.getenv(key, default) # class CloudConfigProvider(ConfigProvider): # 从云配置中心读取配置用于生产 # def __init__(self, endpoint, namespace): # # 初始化配置中心客户端 # pass # def get(self, key: str, defaultNone) - Any: # # 调用配置中心 API # pass # 使用 config EnvConfigProvider() api_key config.get(OPENAI_API_KEY) base_url config.get(OPENAI_BASE_URL, https://api.openai.com/v1)5.2 实现重试与退避机制网络波动或服务端临时过载529 overloaded是常见问题。简单的重试可以大幅提升请求成功率。# retry_handler.py import time from openai import OpenAI, APIError, RateLimitError, APIConnectionError def create_chat_completion_with_retry(client: OpenAI, max_retries3, **kwargs): 带指数退避重试的聊天补全函数 last_exception None for attempt in range(max_retries): try: return client.chat.completions.create(**kwargs) except (APIConnectionError, RateLimitError, APIError) as e: last_exception e # 429 是速率限制错误529 是服务过载其他 APIError 也可能需要重试 if isinstance(e, RateLimitError) or (hasattr(e, status_code) and e.status_code in [429, 529]): wait_time (2 ** attempt) 1 # 指数退避1, 3, 7 秒... print(f请求失败 ({e}). 第 {attempt1} 次重试等待 {wait_time} 秒...) time.sleep(wait_time) else: # 对于非重试性错误如认证失败400直接抛出 raise e # 所有重试都失败 raise Exception(f所有 {max_retries} 次重试均失败。最后错误: {last_exception}) # 使用示例 # response create_chat_completion_with_retry(client, max_retries3, modelgpt-3.5-turbo, messages[...])5.3 上下文长度管理与令牌计数超出上下文长度会直接导致400 this models maximum context length is...错误。必须在发送请求前估算令牌数。# token_management.py import tiktoken # OpenAI 官方的令牌计数库 def num_tokens_from_messages(messages, modelgpt-3.5-turbo-0613): 根据消息列表计算近似令牌数 (OpenAI 格式) try: encoding tiktoken.encoding_for_model(model) except KeyError: print(f未找到模型 {model} 的编码使用 cl100k_base 编码。) encoding tiktoken.get_encoding(cl100k_base) tokens_per_message 3 # 每条消息的开销 tokens_per_name 1 # 如果角色有名字每个名字的开销 num_tokens 0 for message in messages: num_tokens tokens_per_message for key, value in message.items(): if value is not None: num_tokens len(encoding.encode(value)) if key name: num_tokens tokens_per_name num_tokens 3 # 每次回复的开销 return num_tokens # 使用示例 messages [ {role: system, content: 你是一个助手。}, {role: user, content: 这是一段很长的用户输入... * 10} ] token_count num_tokens_from_messages(messages, modelgpt-4o) print(f预计令牌数: {token_count}) MAX_TOKENS 128000 # 假设模型最大上下文为 128k if token_count MAX_TOKENS * 0.9: # 预留10%给生成 print(警告上下文长度接近限制需要裁剪或总结历史消息。) # 实现消息裁剪逻辑例如保留最近 N 条或总结旧消息对于非 OpenAI 模型需要查看其官方文档看是否有对应的令牌计算 SDK或者使用近似估算。5.4 异步调用提升吞吐量对于需要同时处理多个请求的后端服务使用异步 I/O 可以极大提升吞吐量避免因等待单个 API 响应而阻塞。# async_demo.py import asyncio import os from openai import AsyncOpenAI from dotenv import load_dotenv load_dotenv() client AsyncOpenAI(api_keyos.getenv(OPENAI_API_KEY)) async def ask_question(question: str): 异步提问函数 try: response await client.chat.completions.create( modelgpt-3.5-turbo, messages[{role: user, content: question}], max_tokens50, ) return response.choices[0].message.content except Exception as e: return f错误: {e} async def main(): questions [ Python 是什么, 如何学习编程, 解释一下 RESTful API。 ] # 并发发起多个请求 tasks [ask_question(q) for q in questions] answers await asyncio.gather(*tasks) for q, a in zip(questions, answers): print(fQ: {q}) print(fA: {a[:60]}...) # 截断显示 print(- * 40) if __name__ __main__: asyncio.run(main())6. 常见错误排查与解决方案在实际调用中你会遇到各种各样的错误。下面是一个速查表帮助你快速定位和解决问题。错误现象 / 状态码可能原因检查与解决方案APIError: 401API Key 无效、过期或未提供。1. 检查.env文件中的API_KEY变量名和值是否正确。2. 确认 Key 是否有调用权限或是否已过期。3. 在代码中打印os.getenv(API_KEY)的前几位确认已加载。APIError: 400 type must be in [enabled, disabled, auto]请求参数中某个字段的type值不合法。常见于调用 Claude API 时tool_choice等参数格式错误。1. 仔细阅读对应 API 提供商的官方文档确认参数tool_choice或类似参数的可选值。2. 检查请求体 JSON确保type字段的值是文档中明确列出的。APIError: 400 this models maximum context length is...输入的提示Prompt加上要求的最大输出令牌数超过了模型限制。1. 使用tiktoken或类似库计算输入消息的令牌数。2. 减少max_tokens参数值。3. 裁剪或总结历史对话消息。4. 换用上下文长度更大的模型。APIError: 400 the supported api model names are...请求中指定的model参数不被该 API 端点支持。1.这是最常见的原因确认你调用的端点base_url和模型名model是否匹配。例如向 DeepSeek 端点发送model“gpt-4”就会报此错。2. 查阅该提供商的最新模型列表使用正确的模型标识符。APIError: 402 insufficient balance账户余额不足。登录对应平台的控制台为账户充值。APIError: 429 Rate limit exceeded超出速率限制每分钟/每天请求数或令牌数。1. 实现指数退避重试机制见 5.2。2. 降低请求频率。3. 申请提升速率限制付费用户。APIError: 529 overloaded服务端过载通常是临时性问题。1. 实现重试机制见 5.2。2. 稍后再试。APIConnectionError/ConnectionRefused网络连接失败无法到达 API 服务器。1. 检查本地网络。2. 确认base_url是否正确。3. 如果是调用海外 API检查网络连通性。4. 检查防火墙或代理设置。ChooseImage:fail api scope is not declared...这是小程序等平台特有的错误与 LLM API 无关是权限配置问题。在小程序管理后台的“开发-开发管理-接口设置”中添加所需 API 的权限。Login failed. Check API token or GitLab version...这是 GitLab CI/CD 等场景的错误与 LLM API 无关是 CI 令牌或版本问题。检查 CI 配置中的API_TOKEN和 GitLab 版本兼容性。响应不完整connection closed mid-response网络连接在流式传输过程中中断。1. 检查客户端和服务端的网络稳定性。2. 增加超时设置。3. 对于非关键任务可以考虑捕获异常并记录不完整响应。流式响应缓慢或卡顿模型生成速度慢或网络延迟高。1. 这是正常现象复杂问题需要更长的推理时间。2. 可以考虑换用推理速度更快的模型如gpt-3.5-turbo比gpt-4快。3. 检查是否有其他进程占用大量带宽。6.1 通用排查清单当遇到未知错误时按以下顺序排查检查基础配置API Key、base_url、model参数是否正确无误环境变量是否成功加载简化请求用一个最简单的请求如单轮对话max_tokens很小测试看是否是复杂参数导致的问题。查看完整错误信息捕获异常并打印完整的错误对象。很多库如openai的错误对象包含了丰富的status_code、message、body等信息。try: response client.chat.completions.create(...) except Exception as e: print(f错误类型: {type(e)}) print(f错误信息: {e}) if hasattr(e, status_code): print(f状态码: {e.status_code}) if hasattr(e, body): print(f响应体: {e.body}) # 记录日志查阅官方文档和状态页访问对应服务商的官方文档确认 API 格式、参数和模型列表。同时查看服务状态页如 OpenAI Status 确认服务是否出现故障。社区搜索将错误信息的关键部分复制到搜索引擎或技术社区如 Stack Overflow, GitHub Issues中搜索很可能已有解决方案。7. 进阶话题与扩展方向掌握了基础调用和错误处理后你可以进一步优化你的集成方案。7.1 使用 API 中转站对于一些网络访问不便的场景或者为了统一管理多个 API 提供商可以使用 API 中转服务。中转站会提供一个统一的入口背后帮你路由到不同的模型服务。注意事项安全性选择信誉良好的中转服务因为你的 API Key 和请求数据会经过他们。兼容性确认中转站支持的模型列表和 API 格式是否与你的客户端兼容通常是 OpenAI 格式。成本中转服务可能会加收费用。配置使用时只需将代码中的base_url改为中转站提供的地址并可能使用中转站提供的专属 API Key。7.2 构建简单的负载均衡与降级策略当你有多个同类型模型的 API Key例如多个 OpenAI 组织账号或多个可用的模型时可以实现简单的负载均衡和故障转移。# simple_load_balancer.py import random from typing import List from openai import OpenAI class MultiClientManager: def __init__(self, api_keys: List[str], base_url: str): self.clients [OpenAI(api_keykey, base_urlbase_url) for key in api_keys] def get_client(self, strategy: str round_robin): 获取一个客户端实例 if strategy random: return random.choice(self.clients) elif strategy round_robin: # 简单实现轮询生产环境需考虑线程安全 client self.clients[self.current_index] self.current_index (self.current_index 1) % len(self.clients) return client else: return self.clients[0] def create_chat_completion_with_fallback(self, **kwargs): 带故障转移的调用 last_error None for client in self.clients: try: return client.chat.completions.create(**kwargs) except Exception as e: print(fClient failed: {e}) last_error e continue # 尝试下一个客户端 raise Exception(fAll clients failed. Last error: {last_error}) # 使用示例 # manager MultiClientManager([key1, key2, key3], https://api.openai.com/v1) # response manager.create_chat_completion_with_fallback(modelgpt-3.5-turbo, messages[...])7.3 监控与日志记录在生产环境中必须记录每一次 API 调用的详细信息用于监控成本、性能和故障排查。# logging_setup.py import logging import json from datetime import datetime def setup_api_logger(): logger logging.getLogger(llm_api) logger.setLevel(logging.INFO) # 文件处理器记录详细日志 fh logging.FileHandler(llm_api.log) formatter logging.Formatter(%(asctime)s - %(name)s - %(levelname)s - %(message)s) fh.setFormatter(formatter) logger.addHandler(fh) # 控制台处理器只记录错误 ch logging.StreamHandler() ch.setLevel(logging.ERROR) logger.addHandler(ch) return logger logger setup_api_logger() def log_api_call(model, prompt_tokens, completion_tokens, total_tokens, cost_estimate, duration, successTrue, error_msg): 记录一次 API 调用的关键指标 log_entry { timestamp: datetime.utcnow().isoformat(), model: model, usage: { prompt_tokens: prompt_tokens, completion_tokens: completion_tokens, total_tokens: total_tokens, }, cost_estimate_usd: cost_estimate, # 根据提供商单价估算 duration_seconds: duration, success: success, } if not success: log_entry[error] error_msg logger.info(json.dumps(log_entry)) # 在每次 API 调用前后记录 # start_time time.time() # try: # response client.chat.completions.create(...) # end_time time.time() # log_api_call(modelmodel, prompt_tokensresponse.usage.prompt_tokens, ...) # except Exception as e: # log_api_call(..., successFalse, error_msgstr(e))通过系统化的日志你可以分析 token 消耗模式、识别异常调用、进行成本审计。集成大模型 API 是一个从简单调用到复杂工程实践的持续过程。从确保每一次基础请求的成功到为生产环境构建稳定、高效、可观测的集成方案每一步都需要对 API 机制、错误处理和系统设计有深入的理解。建议从本文的最小案例出发逐步引入重试、异步、监控等组件并根据你的具体业务需求如上下文管理、工具调用、多模态处理进行深度定制。始终记住仔细阅读官方文档、编写具有防御性的代码异常处理、参数校验以及建立完善的监控告警体系是保障 AI 应用稳定运行的三大基石。