在 AI 应用开发领域，将大模型能力集成到现有产品中已成为提升用户体验和功能创新的关键路径。无论是 Claude 内置浏览器带来的上下文感知，Google 搜索与应用的无缝衔接，还是 Spotify 这类娱乐平台对 AI 的探索，其背后都离不开一套稳定、高效的 API 集成与调用机制。对于开发者而言，理解如何在自己的项目中接入这些 AI 服务，处理常见的 API 错误，并构建一个健壮的 AI 功能模块，是当前必须掌握的核心技能。

本文将以一个开发者视角，带你从零开始，完成一个集成 AI 大模型 API 的示例项目。我们将聚焦于 API 调用的全流程：从环境准备、密钥配置、请求构造，到响应处理、错误排查以及生产环境的最佳实践。你会学习到如何处理诸如上下文长度超限、连接中断、模型不可用等典型错误，并了解如何设计代码结构以适配不同的 AI 服务提供商。无论你是想为现有应用添加智能对话、内容摘要还是代码生成功能，这篇文章都将提供一套可复现、可排查的工程化方案。

1. 理解 AI API 集成的基本架构与核心概念

在动手写代码之前，我们需要厘清几个关键概念，这决定了后续代码的结构和错误处理逻辑。

1.1 AI API 服务提供商与模型

目前主流的大模型 API 服务由几家头部公司提供，它们各自有不同的模型、定价和接口规范。常见的包括：

• OpenAI API: 提供 GPT-4、GPT-3.5-Turbo 等模型，接口相对成熟，文档完善。
• Anthropic Claude API: 提供 Claude 3 系列模型，以长上下文和强推理能力著称。
• Google Gemini API: 提供 Gemini Pro、Flash 等模型，深度集成于 Google 生态。
• DeepSeek API: 提供 DeepSeek-V4-Pro、DeepSeek-V4-Flash 等模型，性价比较高。

你的应用需要根据功能需求、成本预算和性能要求选择合适的提供商和模型。一个重要的趋势是，许多应用开始支持多模型后端，允许用户或系统根据场景切换。

1.2 API 请求与响应的核心要素

一次典型的 AI API 调用包含以下几个核心部分：

• API 密钥 (API Key): 身份验证凭证，必须妥善保管，不应硬编码在客户端代码中。
• 端点 (Endpoint): 服务地址，例如https://api.openai.com/v1/chat/completions。
• 请求体 (Request Body): 通常是一个 JSON 对象，包含model（指定模型）、messages（对话历史）、max_tokens（生成最大长度）等参数。
• 响应体 (Response Body): 同样是一个 JSON 对象，包含 AI 生成的文本、使用的 token 数量等信息。
• 上下文长度 (Context Length): 模型能处理的输入和输出 token 总数上限。这是导致400错误的一个常见原因。

1.3 常见的集成模式

根据应用场景，集成模式主要分为两种：

1. 直接调用模式: 你的后端服务器直接向 AI 服务商的 API 发起请求。这种方式控制力强，但需要处理网络、鉴权、限流等问题。
2. 代理/中转模式: 通过一个自建或第三方的 API 中转站来调用 AI 服务。这可以用于统一接口、缓存、负载均衡或访问某些区域受限的服务。但会引入额外的依赖和故障点。

本文将主要讲解直接调用模式，这是最基础也是最需要掌握的方式。

2. 环境准备与项目初始化

我们将使用 Python 作为演示语言，因为它拥有最丰富的 AI 相关库和社区支持。项目目标是构建一个简单的命令行聊天工具，能够切换不同的 AI 后端。

2.1 开发环境与工具

• Python: 版本 3.8 或以上。确保python和pip命令可用。
• 代码编辑器: VS Code 是很好的选择，可以安装相关插件提升效率。
• 虚拟环境: 使用venv或conda创建独立的 Python 环境，避免包冲突。

首先，创建项目目录并初始化虚拟环境：

# 创建项目目录 mkdir ai_api_integration_demo cd ai_api_integration_demo # 创建并激活虚拟环境 (Linux/macOS) python3 -m venv venv source venv/bin/activate # 创建并激活虚拟环境 (Windows) python -m venv venv venv\Scripts\activate

激活后，命令行提示符前应出现(venv)标识。

2.2 核心依赖安装

我们需要安装用于发起 HTTP 请求的库。requests库简单易用，是入门首选。对于更复杂的生产场景，可以考虑aiohttp（异步）或各服务商提供的官方 SDK。

# 安装 requests 库 pip install requests # 可选：安装用于美化 JSON 输出的库 pip install rich

2.3 获取 API 密钥

要调用任何 AI 服务，你都需要在其开发者平台注册并获取 API Key。

• OpenAI: 访问 platform.openai.com ，在 “API Keys” 页面创建。
• Anthropic (Claude): 访问 console.anthropic.com ，在 “Get API Keys” 页面创建。
• Google AI Studio (Gemini): 访问 aistudio.google.com ，在 “Get API Key” 页面创建。
• DeepSeek: 访问 platform.deepseek.com ，在 “API Keys” 页面创建。

重要安全提示：API Key 是付费凭证，拥有你账户的权限和额度。绝对不要将其提交到 Git 仓库或写入前端代码。下一步我们将学习如何安全地管理它。

3. 构建可配置的多模型 AI 客户端

我们将设计一个AIClient类，它可以根据配置，使用不同的 API 密钥和端点与不同的模型通信。

3.1 项目结构与配置文件

创建以下目录和文件：

ai_api_integration_demo/ ├── .gitignore # 忽略 venv 和 config.ini ├── config.ini.example # 配置文件示例 ├── config.ini # 实际的配置文件（本地创建，不上传） ├── ai_client.py # 核心 AI 客户端类 └── main.py # 主程序入口

首先，创建.gitignore文件，确保敏感信息不上传：

# .gitignore venv/ __pycache__/ *.pyc config.ini .DS_Store

然后，创建config.ini.example作为配置模板。团队成员可以复制此文件为config.ini并填入自己的密钥。

; config.ini.example [API_KEYS] ; 在这里填入你的 API 密钥，不要上传此文件到仓库 openai_api_key = your_openai_api_key_here anthropic_api_key = your_anthropic_api_key_here google_api_key = your_google_api_key_here deepseek_api_key = your_deepseek_api_key_here [DEFAULT] ; 默认使用的模型 default_model = gpt-3.5-turbo ; 默认生成的最大 token 数 default_max_tokens = 500

每个开发者需要手动创建config.ini并填写真实的密钥。

3.2 实现核心的 AIClient 类

现在，在ai_client.py中实现我们的客户端。这个类的核心职责是：根据模型名称，构造正确的 HTTP 请求，发送并处理响应。

# ai_client.py import configparser import json from typing import Dict, List, Optional import requests class AIClient: """一个支持多后端的 AI API 客户端。""" # 定义各 API 的端点 URL _API_ENDPOINTS = { 'openai': 'https://api.openai.com/v1/chat/completions', 'anthropic': 'https://api.anthropic.com/v1/messages', 'google': 'https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent', 'deepseek': 'https://api.deepseek.com/chat/completions', } # 定义模型到其提供商的映射 _MODEL_PROVIDER_MAP = { # OpenAI 'gpt-4': 'openai', 'gpt-3.5-turbo': 'openai', # Anthropic 'claude-3-opus-20240229': 'anthropic', 'claude-3-sonnet-20240229': 'anthropic', # Google 'gemini-pro': 'google', 'gemini-flash': 'google', # DeepSeek 'deepseek-chat': 'deepseek', 'deepseek-coder': 'deepseek', } def __init__(self, config_path: str = 'config.ini'): """初始化客户端，加载配置。 Args: config_path: 配置文件路径。 """ self.config = configparser.ConfigParser() self.config.read(config_path) self.api_keys = {} if 'API_KEYS' in self.config: self.api_keys = dict(self.config['API_KEYS']) self.default_model = self.config.get('DEFAULT', 'default_model', fallback='gpt-3.5-turbo') self.default_max_tokens = self.config.getint('DEFAULT', 'default_max_tokens', fallback=500) def _get_provider(self, model: str) -> str: """根据模型名称获取其提供商。""" provider = self._MODEL_PROVIDER_MAP.get(model) if not provider: raise ValueError(f"不支持的模型: {model}。支持的模型有: {list(self._MODEL_PROVIDER_MAP.keys())}") return provider def _build_request(self, provider: str, model: str, messages: List[Dict], max_tokens: int) -> tuple: """根据提供商构建请求的 URL、Headers 和 Body。""" api_key = self.api_keys.get(f"{provider}_api_key") if not api_key: raise ValueError(f"未找到 {provider} 的 API 密钥，请在 config.ini 中配置。") endpoint = self._API_ENDPOINTS[provider] headers = {} data = {} if provider == 'openai': headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json', } data = { 'model': model, 'messages': messages, 'max_tokens': max_tokens, 'temperature': 0.7, } endpoint = endpoint # 直接使用 elif provider == 'anthropic': headers = { 'x-api-key': api_key, 'anthropic-version': '2023-06-01', 'Content-Type': 'application/json', } # Anthropic 的 messages 格式略有不同 data = { 'model': model, 'max_tokens': max_tokens, 'messages': messages, } endpoint = endpoint # 直接使用 elif provider == 'google': headers = { 'Content-Type': 'application/json', } data = { 'contents': [{'parts': [{'text': msg['content']}] for msg in messages}], 'generationConfig': { 'maxOutputTokens': max_tokens, } } # Google 的端点需要嵌入模型名 endpoint = endpoint.format(model=model) # Google 使用 API Key 作为查询参数 endpoint = f"{endpoint}?key={api_key}" elif provider == 'deepseek': headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json', } data = { 'model': model, 'messages': messages, 'max_tokens': max_tokens, } endpoint = endpoint # 直接使用 return endpoint, headers, data def chat_completion(self, prompt: str, model: Optional[str] = None, max_tokens: Optional[int] = None, system_prompt: str = "你是一个有帮助的AI助手。") -> str: """发送聊天请求并返回 AI 的回复文本。 Args: prompt: 用户输入的问题或指令。 model: 使用的模型名称，如未指定则使用默认模型。 max_tokens: 生成的最大 token 数。 system_prompt: 系统指令，用于设定 AI 的角色。 Returns: AI 生成的回复文本。 Raises: ValueError: 模型不支持或密钥未配置。 requests.exceptions.RequestException: 网络或 API 请求错误。 """ model = model or self.default_model max_tokens = max_tokens or self.default_max_tokens provider = self._get_provider(model) # 构造 messages 列表 messages = [{'role': 'system', 'content': system_prompt}] if prompt: messages.append({'role': 'user', 'content': prompt}) endpoint, headers, data = self._build_request(provider, model, messages, max_tokens) try: response = requests.post(endpoint, headers=headers, json=data, timeout=30) response.raise_for_status() # 如果状态码不是 200，抛出 HTTPError result = response.json() # 根据不同提供商的响应结构提取文本 if provider == 'openai' or provider == 'deepseek': ai_response = result['choices'][0]['message']['content'] elif provider == 'anthropic': ai_response = result['content'][0]['text'] elif provider == 'google': ai_response = result['candidates'][0]['content']['parts'][0]['text'] else: ai_response = str(result) # 兜底 return ai_response.strip() except requests.exceptions.Timeout: raise Exception(f"请求超时，请检查网络或稍后重试。") except requests.exceptions.ConnectionError: raise Exception(f"网络连接错误，请检查网络设置。") except requests.exceptions.HTTPError as e: # 这里会捕获到 400, 401, 429, 500 等错误 self._handle_http_error(e, response) except json.JSONDecodeError: raise Exception(f"API 返回了非 JSON 格式的响应: {response.text[:200]}") def _handle_http_error(self, error: requests.exceptions.HTTPError, response: requests.Response): """处理 HTTP 错误，提供更友好的错误信息。""" status_code = response.status_code try: error_detail = response.json() except: error_detail = {'error': {'message': response.text[:500]}} error_msg = error_detail.get('error', {}).get('message', str(error_detail)) if status_code == 400: # 处理常见的 400 错误 if 'maximum context length' in error_msg.lower(): raise ValueError(f"错误：上下文长度超限。{error_msg} 请减少输入文本或 max_tokens 参数。") elif 'type' in error_msg and 'must be in' in error_msg: # 例如: 'type' must be in ["enabled", "disabled", "auto"] raise ValueError(f"错误：请求参数值无效。{error_msg} 请检查 API 文档。") else: raise ValueError(f"错误：请求参数有误 (400)。详情: {error_msg}") elif status_code == 401: raise PermissionError(f"错误：API 密钥无效或未授权 (401)。请检查 config.ini 中的密钥配置。") elif status_code == 429: raise Exception(f"错误：请求过于频繁，触发限流 (429)。请稍后重试。详情: {error_msg}") elif status_code == 404: raise ValueError(f"错误：请求的端点或模型不存在 (404)。请检查模型名称和端点 URL。") elif 500 <= status_code < 600: raise Exception(f"错误：AI 服务提供商服务器内部错误 ({status_code})。请稍后重试。") else: raise Exception(f"HTTP 请求失败，状态码: {status_code}。详情: {error_msg}")

这个AIClient类完成了以下关键工作：

1. 配置管理：从config.ini安全地读取各平台的 API 密钥。
2. 模型路由：根据输入的模型名称，自动判断使用哪个提供商的 API。
3. 请求构造：为每个提供商构造符合其规范的 HTTP 请求头、请求体和端点。
4. 统一响应解析：处理不同提供商返回的 JSON 数据结构，提取出统一的回复文本。
5. 错误处理：对常见的 HTTP 错误（特别是 400 错误）进行精细化处理，给出可操作的提示。

4. 编写主程序并进行功能验证

有了核心客户端，我们可以编写一个简单的主程序来测试它。

4.1 实现交互式聊天主程序

在main.py中，我们创建一个简单的循环，让用户可以选择模型并连续对话。

# main.py import sys from ai_client import AIClient def main(): print("初始化 AI 客户端...") try: client = AIClient() except FileNotFoundError: print("错误：未找到配置文件 'config.ini'。") print("请复制 'config.ini.example' 为 'config.ini' 并填入你的 API 密钥。") sys.exit(1) except Exception as e: print(f"初始化客户端时出错: {e}") sys.exit(1) print("客户端初始化成功！") print("支持以下模型:") for model in client._MODEL_PROVIDER_MAP.keys(): print(f" - {model}") current_model = client.default_model print(f"\n当前默认模型: {current_model}") print("输入 '/model 模型名' 切换模型，例如 '/model gpt-4'") print("输入 '/quit' 或 '/exit' 退出程序。") print("-" * 50) # 简单的对话历史（仅用于演示，实际长对话需管理上下文） conversation_history = [] while True: try: user_input = input("\nYou: ").strip() if not user_input: continue # 处理命令 if user_input.startswith('/'): if user_input in ['/quit', '/exit']: print("再见！") break elif user_input.startswith('/model '): new_model = user_input.split(' ', 1)[1] if new_model in client._MODEL_PROVIDER_MAP: current_model = new_model print(f"已切换模型至: {current_model}") else: print(f"错误：不支持的模型 '{new_model}'") else: print(f"未知命令: {user_input}") continue # 发送请求 print(f"AI ({current_model}) 正在思考...") try: # 在实际项目中，应将 conversation_history 作为 messages 传入 # 此处为简化，每次只发送当前问题 response = client.chat_completion( prompt=user_input, model=current_model, max_tokens=client.default_max_tokens ) print(f"\nAI: {response}") # 可选：将对话存入历史 conversation_history.append({'role': 'user', 'content': user_input}) conversation_history.append({'role': 'assistant', 'content': response}) except ValueError as e: # 处理参数错误、上下文超长等 print(f"参数错误: {e}") except PermissionError as e: # 处理鉴权错误 print(f"鉴权失败: {e}") print("请检查你的 API 密钥是否有效且未过期。") except Exception as e: # 处理其他所有异常 print(f"请求过程中发生错误: {e}") except KeyboardInterrupt: print("\n\n程序被中断。") break except EOFError: print("\n\n输入结束。") break if __name__ == "__main__": main()

4.2 运行与验证

1. 准备配置文件：将config.ini.example复制为config.ini，并填入你至少一个有效的 API 密钥（例如 OpenAI 的）。

   cp config.ini.example config.ini # 然后用文本编辑器编辑 config.ini，填入你的 openai_api_key

2. 运行程序：

   python main.py

3. 验证功能：

   • 程序启动后，应显示支持的模型列表。
   • 输入普通问题，如“你好，请介绍下你自己”，应能收到 AI 的回复。
   • 尝试切换模型命令/model gpt-3.5-turbo（确保已配置对应密钥）。
   • 输入/quit退出程序。

预期成功输出示例：

初始化 AI 客户端... 客户端初始化成功！ 支持以下模型: - gpt-4 - gpt-3.5-turbo - claude-3-opus-20240229 - claude-3-sonnet-20240229 - gemini-pro - gemini-flash - deepseek-chat - deepseek-coder 当前默认模型: gpt-3.5-turbo 输入 '/model 模型名' 切换模型，例如 '/model gpt-4' 输入 '/quit' 或 '/exit' 退出程序。 -------------------------------------------------- You: 你好，请用一句话介绍 Python。 AI (gpt-3.5-turbo) 正在思考... AI: Python 是一种高级、解释型、通用的编程语言，以其简洁明了的语法和强大的标准库而闻名，广泛应用于Web开发、数据分析、人工智能和科学计算等领域。 You: /model gemini-pro 已切换模型至: gemini-pro You: 再问一次，Python 是什么？ AI (gemini-pro) 正在思考... AI: Python 是一种高级、解释型、通用的编程语言，强调代码的可读性和简洁性。

如果一切顺利，说明你的基础 API 集成已经成功。接下来，我们需要深入处理那些在实际开发中必然会遇到的错误。

5. 深度排查：处理典型 API 错误与连接问题

集成第三方 API 时，网络错误、参数错误和限流是最常见的挑战。我们的_handle_http_error方法已经处理了一部分，但我们需要更系统地理解它们。

5.1 上下文长度超限错误 (Context Length Exceeded)

这是最常见的400 Bad Request错误之一。每个模型都有固定的上下文窗口（例如 4K, 16K, 128K, 1M tokens）。当你的请求（系统提示词 + 对话历史 + 用户问题 + 预留的回复空间）超过这个限制时，API 会拒绝请求。

错误信息特征：

API error: 400 This model's maximum context length is 1048576 tokens. However, your messages resulted in 1200000 tokens.

排查与解决步骤：

1. 计算 Token 数量：在发送请求前，可以粗略估算。对于英文，1个token约等于0.75个单词或4个字符。中文更复杂，1个汉字可能对应1.5-2个token。可以使用模型的tiktoken（OpenAI）或类似库进行精确计算。
2. 精简输入：
   • 缩短系统提示词。
   • 对长的对话历史进行摘要或选择性保留最近几轮。
   • 让用户输入更简洁的问题。
3. 选择更大窗口的模型：例如从gpt-3.5-turbo（16K）切换到claude-3-sonnet（200K）或gpt-4-128k。
4. 代码层面的预防：在客户端中添加一个预检查函数。

# 在 AIClient 类中添加 def estimate_tokens(self, text: str, model: str) -> int: """非常粗略的 token 估算。生产环境应使用对应模型的 tokenizer。""" # 这是一个简单估算，英文按单词，中文按字符 # 实际请使用 tiktoken (OpenAI) 或 anthropic 的 tokenizer import re words = re.findall(r'\w+', text) chinese_chars = re.findall(r'[\u4e00-\u9fff]', text) # 非常粗略的估算：英文单词算1个token，中文字符算2个token estimated_tokens = len(words) + len(chinese_chars) * 2 return estimated_tokens def is_context_too_long(self, messages: List[Dict], model: str, max_tokens_to_generate: int) -> bool: """检查上下文是否可能超限。""" total_text = " ".join([msg['content'] for msg in messages]) estimated_input_tokens = self.estimate_tokens(total_text, model) # 为输出预留空间 estimated_total_tokens = estimated_input_tokens + max_tokens_to_generate # 这里需要维护一个模型上下文长度映射表 model_context_window = { 'gpt-3.5-turbo': 16385, 'gpt-4': 8192, 'gpt-4-128k': 128000, 'claude-3-sonnet-20240229': 200000, 'gemini-pro': 32768, # ... 其他模型 } window = model_context_window.get(model, 4096) # 默认一个安全值 return estimated_total_tokens > window * 0.9 # 留 10% 缓冲

5.2 连接错误与超时

网络不稳定、代理设置、服务端问题都可能导致连接错误。

常见错误信息：

requests.exceptions.ConnectionError: ... [Errno 61] Connection refused API error: Connection closed mid-response. The response above may be incomplete. Unable to connect to API (ECONNRESET)

排查清单：

1. 检查网络连通性：使用ping或curl测试是否能访问 API 域名（如api.openai.com）。注意，某些网络环境可能对特定域名有访问限制。
2. 检查代理设置：如果你的环境需要通过代理访问外网，需要在代码中或系统环境变量中配置。

   # 在 requests.post 中设置代理 proxies = { 'http': 'http://your-proxy:port', 'https': 'http://your-proxy:port', } response = requests.post(endpoint, headers=headers, json=data, proxies=proxies, timeout=30)

3. 调整超时时间：默认的timeout=30可能在某些慢网络下不够。可以适当增加，并区分连接超时和读取超时。

   response = requests.post(endpoint, headers=headers, json=data, timeout=(10, 60)) # (连接超时, 读取超时)

4. 实现重试机制：对于瞬时的网络抖动或服务端过载（429错误），重试是有效的策略。

   import time from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry def create_session_with_retry(retries=3, backoff_factor=0.5): session = requests.Session() retry_strategy = Retry( total=retries, backoff_factor=backoff_factor, # 重试等待时间：{backoff factor} * (2 ** ({retry number} - 1)) status_forcelist=[429, 500, 502, 503, 504], # 对这些状态码重试 ) adapter = HTTPAdapter(max_retries=retry_strategy) session.mount("http://", adapter) session.mount("https://", adapter) return session # 在 chat_completion 方法中使用 session = create_session_with_retry() response = session.post(endpoint, headers=headers, json=data, timeout=30)

5.3 模型不可用或参数错误

错误信息示例：

Unfortunately, Claude is not available to new users right now. We're working on expanding access. API error: 400 'type' must be in ["enabled", "disabled", "auto"]. The supported API model names are deepseek-v4-pro or deepseek-v4-flash, but you requested 'deepseek-chat'.

排查与解决：

1. 检查模型名称：确保传入的model参数与 API 文档中支持的完全一致。模型名称可能随版本更新而变化。
2. 检查参数值：仔细阅读 API 文档，确保请求体中的每个字段的值都在允许的范围内。例如，某些 API 的stream参数只能是true或false，不能是"true"（字符串）。
3. 检查服务状态：访问 AI 服务提供商的官方状态页面（如 OpenAI Status ），确认服务是否出现中断。
4. 检查账户权限：确保你的 API 密钥对应的账户有权限访问该模型。例如，GPT-4 可能需要对账户单独申请开通。

5.4 密钥无效或额度不足

错误信息：

Error: Incorrect API key provided. Error: You exceeded your current quota, please check your plan and billing details.

排查：

1. 核对密钥：检查config.ini中的密钥是否正确，前后是否有空格。
2. 检查额度：登录相应平台的控制台，查看剩余额度或用量。
3. 检查账单：确保关联的支付方式有效，没有欠费。

6. 生产环境最佳实践与扩展方向

将演示代码用于个人学习没问题，但要用于生产环境，还需要考虑更多因素。

6.1 配置管理安全升级

• 不使用本地文件：在生产环境（如 Docker 容器、云服务器）中，应将 API 密钥存储在环境变量或专业的密钥管理服务（如 AWS Secrets Manager, HashiCorp Vault）中。

  # 从环境变量读取 import os openai_api_key = os.environ.get('OPENAI_API_KEY') if not openai_api_key: raise ValueError("请设置环境变量 OPENAI_API_KEY")

• 密钥轮转：定期更新 API 密钥，并确保应用能无缝切换到新密钥。

6.2 增强鲁棒性

• 熔断与降级：当某个 AI 服务连续失败时，应暂时熔断对该服务的调用，并可以降级到另一个可用的服务或返回一个友好的默认回复。
• 限流与队列：根据你的业务量，在调用 AI API 前实施限流，或将请求放入队列异步处理，避免突发流量触发提供商的限流（429错误）。
• 全面的日志记录：记录每一次请求的模型、输入 token 数、输出 token 数、耗时、是否成功、错误信息。这对于监控成本、排查问题和分析性能至关重要。

6.3 成本与性能优化

• 缓存：对于内容生成类且结果相对固定的请求（例如，将固定产品描述翻译成多种语言），可以将结果缓存起来，避免重复调用产生费用。
• 异步调用：对于不要求实时响应的场景，使用异步 HTTP 客户端（如aiohttp）可以大幅提升吞吐量。
• Token 用量监控：实时计算并监控 token 消耗，设置预算告警。不同模型的输入和输出 token 单价不同。

6.4 扩展为 AI Agent 或复杂工作流

本文的客户端是单次问答。更复杂的应用如 AI Agent，需要：

• 对话历史管理：维护一个不断增长的上下文窗口，并在接近限制时进行智能裁剪或总结。
• 工具调用（Function Calling）：让 AI 能够调用外部工具（查数据库、执行计算、调用其他 API）。这需要按照提供商的规范，在请求中定义工具，并解析 AI 返回的工具调用请求。
• 流式响应（Streaming）：对于生成长文本的场景，使用流式接口可以提升用户体验，实现打字机效果。这需要处理 Server-Sent Events (SSE)。
• 多模态处理：集成图片、音频输入。这需要按照 API 规范对非文本数据进行编码（如 Base64）并构造复杂的请求体。

6.5 统一的错误处理与监控

建立一个中心化的错误处理与监控仪表板，将来自不同 AI 服务的错误进行分类、聚合和告警。这能帮助你快速发现是某个特定服务出了问题，还是你的应用逻辑有缺陷。

通过遵循上述的工程实践，你可以构建出一个不仅能够运行，而且足够健壮、可维护、可扩展的 AI 集成应用。从处理一个简单的 API 调用开始，逐步深入到错误处理、性能优化和架构设计，这是将 AI 能力可靠地转化为产品价值的必经之路。