通用文本对话接口文档

一、简介

本接口通过调用OpenAI兼容的大语言模型生成对话回答，支持预设系统角色与用户提问交互，返回模型生成的中文回复内容。核心功能是根据用户输入的问题，由模型生成符合系统角色设定的响应。

二、请求参数

参数名	类型	必需	说明	示例值
api_key	字符串	是	访问API的密钥，用于身份验证	sk - XyLy**************************mIqSt
base_url	字符串	是	API服务的基础地址，指定模型服务的访问路径	https://api.gravitex.ai
model	字符串	是	用于生成回答的大语言模型标识	claude - sonnet - 4 - 20250514 GPT-4o
messages	数组	是	对话消息列表，包含系统角色定义和用户提问每个元素为对象，包含： - role：角色(user/system/assistant) - content：消息内容	{ "role": "user", "content": "你好" }
temperature	数字	否	控制生成内容的随机性，0 - 2值越高回复随机性越强	0.7

三、返回值说明

函数返回字符串类型结果，包含两种可能：

（一）成功响应

类型：字符串

说明：模型生成的中文回复内容

示例：

人工智能是研究、开发用于模拟、延伸和扩展人的智能的理论、方法、技术及应用系统的一门新的技术科学，它试图了解智能的实质，并生产出一种新的能以人类智能相似的方式做出反应的智能机器。

（二）错误响应

类型：字符串

说明：包含错误原因的描述，可能的情况：

错误：API密钥无效或未授权（密钥验证失败）

错误：模型 claude-sonnet-4-20250514 不存在或不被支持（模型不存在）

错误：无法连接到API服务器（网络或地址错误）

API请求失败：[具体错误信息]（其他API层错误）

发生未知错误：[具体错误信息]（未捕获的异常）

四、错误处理

函数捕获并处理以下异常类型（基于OpenAI Python SDK异常体系）：

异常类型	触发场景	返回信息
AuthenticationError	API密钥无效、过期或未授权	错误：API密钥无效或未授权
NotFoundError	指定的模型ID不存在或不被服务端支持	错误：模型 [model名称] 不存在或不被支持
APIConnectionError	网络中断、base_url错误或服务器未响应	错误：无法连接到API服务器
APIError	API请求格式错误、权限不足等服务端异常	API请求失败：[错误详情]
其他未捕获异常	代码逻辑错误、意外数据格式等	发生未知错误：[错误详情]

五、实现代码

六、使用示例输出

（一）成功输出示例

AI回复内容：
人工智能是研究、开发用于模拟、延伸和扩展人的智能的理论、方法、技术及应用系统的一门新的技术科学，其核心包括机器学习、自然语言处理、计算机视觉等领域，广泛应用于医疗、金融、交通等行业，正深刻改变着人类的生产和生活方式。

（二）错误输出示例

AI回复内容：
错误：API密钥无效或未授权

七、注意事项

代码中api_key、base_url、model等参数为必要值，如需修改需直接调整函数内对应字段。

messages列表包含对话历史，system角色用于设定模型行为，user角色为用户当前提问。

temperature参数建议设置在0 - 2之间，0表示生成内容更确定，2表示更具随机性。

网络稳定性对接口调用成功率影响较大，建议在网络环境良好时使用。

若需扩展为多轮对话，可修改messages参数，追加历史对话记录（包含assistant角色的回复）。

代码依赖openai Python库，使用前需确保已安装（pip install openai ）。

通用文本对话接口文档

一、简介#

二、请求参数#

三、返回值说明#

（一）成功响应#

（二）错误响应#

四、错误处理#

五、实现代码#

六、使用示例输出#

（一）成功输出示例#

（二）错误输出示例#

七、注意事项#