✨ API对接

1. 概述

2. 准备工作

• 注册账户：在OpenAI平台和GLM开放平台注册账户。

• 获取API密钥：分别从OpenAI和GLM平台获取各自的API密钥（API Key）。

• 安装工具或库：
• 命令行工具：如curl。
• 编程语言库：如Python的requests库。

3. OpenAI API 对接

3.1 获取API密钥

1. 注册账户：访问OpenAI注册页面并创建账户。

2. 生成API密钥：
• 登录后，进入API密钥管理页面。
• 点击“创建新密钥”，并将生成的密钥保存到安全的地方。

3.2 API端点

• 基础URL：https://api.openai.com/v1

• 主要端点：
• 聊天完成：POST /v1/chat/completions
• 文本完成：POST /v1/completions
• 编辑：POST /v1/edits
• 嵌入：POST /v1/embeddings
• 文件管理：POST /v1/files

3.3 请求参数详解

• model (string, required)：
• 指定使用的模型名称，如gpt-3.5-turbo或gpt-4。

• messages (array of objects, required)：
• 对话历史，每个对象包含：
• role (string)：system、user或assistant。
• content (string)：消息内容。

• temperature (number, optional)：
• 控制生成文本的随机性，范围0到2。较高的值（如0.8）使输出更具创意，较低的值（如0.2）则更确定和集中。
• 默认值：1

• top_p (number, optional)：
• 另一种控制随机性的参数，基于累积概率。范围0到1。
• 默认值：1

• n (integer, optional)：
• 生成的完成次数。
• 默认值：1

• stream (boolean, optional)：
• 是否启用流式传输响应。
• 默认值：false

• max_tokens (integer, optional)：
• 生成的最大标记数。
• 默认值：根据模型不同而变化。

• stop (string or array, optional)：
• 指定生成完成的停止词。

• presence_penalty (number, optional)：
• 增加新主题出现的概率，范围-2到2。

• frequency_penalty (number, optional)：
• 减少重复内容的概率，范围-2到2。

• user (string, optional)：
• 用于标识用户的字符串，帮助OpenAI监控滥用。

3.4 请求示例

使用curl发送请求

使用Python发送请求

3.5 响应处理

• id (string)：请求的唯一标识符。

• object (string)：对象类型，通常为chat.completion。

• created (integer)：Unix时间戳，表示响应生成时间。

• model (string)：使用的模型名称。

• choices (array)：
• 每个元素包含：
• message (object)：
• role (string)：通常为assistant。
• content (string)：生成的回复内容。
• finish_reason (string)：完成原因，如stop、length等。
• index (integer)：完成的序号。

• usage (object)：
• prompt_tokens (integer)：提示词的标记数。
• completion_tokens (integer)：完成内容的标记数。
• total_tokens (integer)：总标记数。

示例响应

3.6 错误处理

• 400 Bad Request：
• 原因：请求参数有误。
• 解决方案：检查请求参数是否正确，如缺少必需字段或字段类型错误。

• 401 Unauthorized：
• 原因：API密钥无效或未提供。
• 解决方案：确保API密钥正确，并在请求头中正确设置Authorization。

• 403 Forbidden：
• 原因：权限不足，可能API密钥未启用相关权限。
• 解决方案：检查API密钥的权限设置，或联系支持团队。

• 429 Too Many Requests：
• 原因：请求频率超过限制。
• 解决方案：减少请求频率，或等待一段时间后重试。

• 500 Internal Server Error：
• 原因：服务器内部错误。
• 解决方案：稍后重试请求。

示例错误响应

3.7 示例代码

使用Python进行更复杂的请求

4. GLM API 对接

4.1 获取API密钥

1. 注册账户：访问GLM开放平台并创建账户。

2. 生成API密钥：
• 登录后，进入个人中心或API管理页面。
• 创建新的API密钥，并将其保存到安全的地方。

4.2 API端点

• 基础URL：https://open.bigmodel.cn/api/paas/v4

• 主要端点：
• 聊天完成：POST /chat/completions
• 文本完成：POST /text/completions
• 翻译：POST /translate
• 其他自定义任务：根据具体需求参考官方文档。

4.3 请求参数详解

• model (string, required)：
• 指定使用的模型名称，如glm-4。

• messages (array of objects, required)：
• 对话历史，每个对象包含：
• role (string)：user或assistant。
• content (string)：消息内容。

• temperature (number, optional)：
• 控制生成文本的随机性，范围0到2。
• 默认值：1

• top_p (number, optional)：
• 基于累积概率的随机性控制，范围0到1。
• 默认值：1

• n (integer, optional)：
• 生成的完成次数。
• 默认值：1

• max_tokens (integer, optional)：
• 生成的最大标记数。
• 默认值：根据模型不同而变化。

• stop (string or array, optional)：
• 指定生成完成的停止词。

• presence_penalty (number, optional)：
• 增加新主题出现的概率，范围-2到2。

• frequency_penalty (number, optional)：
• 减少重复内容的概率，范围-2到2。

• user (string, optional)：
• 用于标识用户的字符串，帮助监控滥用。

4.4 请求示例

使用curl发送请求

4.5 响应处理

• id (string)：请求的唯一标识符。

• object (string)：对象类型，通常为chat.completion。

• created (integer)：Unix时间戳，表示响应生成时间。

• model (string)：使用的模型名称。

• choices (array)：
• 每个元素包含：
• message (object)：
• role (string)：通常为assistant。
• content (string)：生成的回复内容。
• finish_reason (string)：完成原因，如stop、length等。
• index (integer)：完成的序号。

• usage (object)：
• prompt_tokens (integer)：提示词的标记数。
• completion_tokens (integer)：完成内容的标记数。
• total_tokens (integer)：总标记数。

示例响应

4.6 错误处理

• 400 Bad Request：
• 原因：请求参数有误。
• 解决方案：检查请求参数是否正确，如缺少必需字段或字段类型错误。

• 401 Unauthorized：
• 原因：API密钥无效或未提供。
• 解决方案：确保API密钥正确，并在请求头中正确设置Authorization。

• 403 Forbidden：
• 原因：权限不足，可能API密钥未启用相关权限。
• 解决方案：检查API密钥的权限设置，或联系支持团队。

• 429 Too Many Requests：
• 原因：请求频率超过限制。
• 解决方案：减少请求频率，或等待一段时间后重试。

• 500 Internal Server Error：
• 原因：服务器内部错误。
• 解决方案：稍后重试请求。

示例错误响应

4.7 示例代码

使用Python进行请求

5. Gemini API 对接

5.1 获取API密钥

1. 注册账户：访问Gemini开放平台并创建账户。

2. 生成API密钥：
• 登录后，进入个人中心或API管理页面。
• 创建新的API密钥，并将其保存到安全的地方。

5.2 API端点

• 基础URL：https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-latest:generateContent?key=YOUR_API_KEY

5.3 请求示例

5.4 响应处理

• candidates(array)：
• 每个元素包含：
• content(object)：
• role (string)：通常为model。
• parts(array)：
• text(string)：生成的回复内容。
• finishReason(string)：完成原因，如stop、length等。
• index (integer)：完成的序号。
• safetyRatings(array)：
• category(string)：
• probability(string)：

• usageMetadata(object)：
• promptTokenCount(integer)：提示词的标记数。
• candidatesTokenCount(integer)：完成内容的标记数。
• totalTokenCount(integer)：总标记数。

示例响应

5.5 错误处理

• 400 Bad Request：
• 原因：请求参数有误。
• 解决方案：检查请求参数是否正确，如缺少必需字段或字段类型错误。

• 401 Unauthorized：
• 原因：API密钥无效或未提供。
• 解决方案：确保API密钥正确，并在请求头中正确设置API_KEY。

• 403 Forbidden：
• 原因：权限不足，可能API密钥未启用相关权限。
• 解决方案：检查API密钥的权限设置，或联系支持团队。

• 429 Too Many Requests：
• 原因：请求频率超过限制。
• 解决方案：减少请求频率，或等待一段时间后重试。

• 500 Internal Server Error：
• 原因：服务器内部错误。
• 解决方案：稍后重试请求。

示例错误响应

6. 常见问题与最佳实践

6.1 常见问题

1. 如何处理长对话历史？
• 解决方案：由于API对请求长度有限制（如OpenAI的max_tokens），建议仅包含必要的对话历史，或进行摘要以减少长度。

2. API调用频率限制如何处理？
• 解决方案：遵守API的速率限制，使用指数退避策略（exponential backoff）在遇到429错误时重试请求。

3. 如何确保API密钥的安全？
• 解决方案：不要将API密钥硬编码在客户端应用中，使用服务器端代理进行请求，并将密钥存储在安全的环境变量中。

6.2 最佳实践

• 参数优化：
• 根据具体需求调整temperature和top_p参数，以平衡创造性和一致性。
• 使用max_tokens限制生成内容的长度，控制成本。

• 错误处理：
• 实现全面的错误捕捉机制，处理不同类型的错误并采取相应的措施。

• 安全性：
• 不要在前端代码中暴露API密钥，使用后端服务进行API调用。
• 定期轮换API密钥，防止泄露带来的风险。

• 日志记录与监控：
• 记录API调用的日志，包括请求参数和响应时间，以便监控和调优。

• 使用缓存：
• 对于重复的请求，可以使用缓存机制减少API调用次数，节省成本。

• 遵守使用政策：
• 确保使用API时遵守服务提供商的使用政策和条款，避免违规使用。

7. 附录

7.1 参考链接

• OpenAI API文档：https://platform.openai.com/docs/api-reference

• GLM API文档：https://open.bigmodel.cn/docs

• Gemini API文档：https://ai.google.dev/gemini-api/docs

• Python Requests库：https://requests.readthedocs.io/

• Curl文档：https://curl.se/docs/

7.2 常用工具

• Postman：用于测试API请求的工具。

• Insomnia：另一款强大的API测试工具。

• VSCode插件：如REST Client，用于在编辑器中直接发送HTTP请求。

7.3 术语表

• API（应用程序编程接口）：允许不同软件系统之间进行通信的接口。

• JSON（JavaScript对象表示法）：一种轻量级的数据交换格式，易于人阅读和编写。

• Token（标记）：API使用的基本文本单元，用于计算输入和输出的长度。

• Rate Limit（速率限制）：API对单位时间内允许的请求次数的限制。