人工智能大模型【免费下载链接】openai-pythonThe official Python library for the OpenAI API项目地址https://gitcode.com/GitHub_Trending/op/openai-python点击查看免费下载本篇技术指南以 OpenAI 官方 Python SDKopenai-python仓库中的 Conversations API 参考文档 为核心完整讲解client.conversations资源及其items子资源的全部端点、参数与返回类型并结合 源码实现 与 测试用例 深入剖析底层调用机制。读完本文你将掌握如何用 Python SDK 创建、查询、更新、删除会话及其内部条目items以及如何在同步与异步两种模式下正确使用这些接口。一、资源结构总览Conversations 资源与 Items 子资源在 openai-python 中Conversations 功能由两个层级组成对应 api.md 中列出的两组方法Conversations 主资源类定义见 conversations.pyHTTP 端点SDK 方法返回类型POST /conversationsclient.conversations.create(**params)ConversationGET /conversations/{conversation_id}client.conversations.retrieve(conversation_id)ConversationPOST /conversations/{conversation_id}client.conversations.update(conversation_id, **params)ConversationDELETE /conversations/{conversation_id}client.conversations.delete(conversation_id)ConversationDeletedResourceItems 子资源类定义见 items.pyHTTP 端点SDK 方法返回类型POST /conversations/{conversation_id}/itemsclient.conversations.items.create(conversation_id, **params)ConversationItemListGET /conversations/{conversation_id}/items/{item_id}client.conversations.items.retrieve(item_id, *, conversation_id, **params)ConversationItemGET /conversations/{conversation_id}/itemsclient.conversations.items.list(conversation_id, **params)SyncConversationCursorPage[ConversationItem]DELETE /conversations/{conversation_id}/items/{item_id}client.conversations.items.delete(item_id, *, conversation_id)Conversation从源码结构看Conversations类通过cached_property暴露items属性conversations.py因此在调用时需写成client.conversations.items.xxx。同一套接口还提供了AsyncConversations与AsyncItems异步实现items.py同步与异步方法签名完全一致仅返回类型上异步版本使用AsyncConversationCursorPage。二、类型体系从 Conversation 到 ConversationItem2.1 顶层类型导入原文档列出的全部类型可从单一入口导入定义分散在 types/conversations 目录下from openai.types.conversations import ( ComputerScreenshotContent, Conversation, ConversationDeleted, ConversationDeletedResource, Message, SummaryTextContent, TextContent, InputTextContent, OutputTextContent, RefusalContent, InputImageContent, InputFileContent, )其中Conversation与ConversationDeletedResource是端点级返回模型其余为Message的内容部分content part类型这些内容类型大多与 Responses API 共享例如InputTextContent、OutputTextContent实际对应 response_input_text.py 等模块中的类型。2.2 Conversation会话对象模型Conversation定义见 conversation.py是一个基于BaseModel的 Pydantic 模型字段如下class Conversation(BaseModel): id: str # 会话唯一 ID created_at: int # 创建时间Unix 秒级时间戳 metadata: object # 最多 16 个键值对键最长 64 字符值最长 512 字符 object: Literal[conversation] # 对象类型恒为 conversation注意metadata在返回模型中为object类型而在请求参数模型中则使用专门的Metadata见 shared_params/metadata.py用于在创建/更新时提交结构化附加信息方便后续通过 API 或 Dashboard 检索对象。2.3 ConversationDeletedResource删除结果删除会话后返回的不是Conversation而是ConversationDeletedResource见 conversation_deleted_resource.pyclass ConversationDeletedResource(BaseModel): id: str deleted: bool object: Literal[conversation.deleted]该类型用于确认删除操作是否成功。2.4 Message 与内容联合类型Message定义见 message.py表示“一条发往模型或由模型发出的消息”核心字段id消息唯一 IDcontent: List[Content]消息内容为联合类型列表roleunknown、user、assistant、system、critic、discriminator、developer、tool之一statusin_progress、completed、incomplete之一经 API 返回时填充type恒为messagephase可选将 assistant 消息标记为commentary中间评论或final_answer最终回答。Content是带type判别器的联合类型包含 ResponseInputText、ResponseOutputText、TextContent、SummaryTextContent、ContentReasoningText、ResponseOutputRefusal、ResponseInputImage、ComputerScreenshotContent、ResponseInputFile等。这正是 api.md 中列出InputTextContent、OutputTextContent、RefusalContent、InputImageContent、InputFileContent等类型的缘由。2.5 ConversationItem会话内条目的联合类型ConversationItem见 conversation_item.py是带type判别器的 26 个成员的大型TypeAlias联合除Message外还包括 Responses API 的各类工具调用条目ResponseFunctionToolCallItem、ResponseFunctionToolCallOutputItemResponseFileSearchToolCall、ResponseFunctionWebSearch、ResponseToolSearchCall及其输出ImageGenerationCall、ResponseComputerToolCall及其输出ResponseConfigurationUpdateItem、ResponseReasoningItem、ResponseCompactionItemResponseCodeInterpreterToolCall、ResponseApplyPatchToolCall及其输出Program/ProgramOutput、LocalShellCall/LocalShellCallOutputResponseFunctionShellToolCall及其输出MCP 相关McpListTools、McpApprovalRequest、McpApprovalResponse、McpCallAdditionalTools、ResponseCustomToolCall及其输出这意味着一个 Conversation 中可以容纳完整的多模态、多工具交互历史而不仅是文本消息。三、创建会话client.conversations.create方法签名同步版见 conversations.pyclient.conversations.create( *, items: Iterable[ResponseInputItemParam] | Omit omit, metadata: Metadata | Omit omit, extra_headers: Headers | None None, extra_query: Query | None None, extra_body: Body | None None, timeout: float | httpx2.Timeout | None | NotGiven not_given, ) - Conversation参数说明items可选会话上下文的初始条目一次最多添加 20 个条目元素类型为ResponseInputItemParam即 Responses API 的输入条目参数见 response_input_item_param.py。metadata可选最多 16 个键值对键最长 64 字符、值最长 512 字符。extra_headers/extra_query/extra_body向请求追加额外请求头、查询参数与 JSON 属性且其优先级高于客户端或方法级默认值。timeout覆盖客户端级默认超时秒支持传入httpx2.Timeout。源码级调用链create内部调用self._post(/conversations, ...)请求体通过maybe_transform按 conversation_create_params.py 的ConversationCreateParamsTypedDict 校验并序列化同时声明security{bearer_auth: True}即该端点使用 Bearer Token 认证响应按Conversation模型反序列化。同步与异步测试中的最小调用见 test_conversations.pyconversation client.conversations.create()传入全部可选参数items metadata的完整示例conversation client.conversations.create( items[ { content: string, role: user, phase: commentary, type: message, } ], metadata{foo: string}, )异步版本用法一致仅需将客户端换为AsyncOpenAI并awaitconversation await async_client.conversations.create( metadata{project: demo}, )四、检索与更新会话4.1 retrieve获取单个会话client.conversations.retrieve( conversation_id, # 必填会话 ID *, extra_headersNone, extra_queryNone, extra_bodyNone, timeoutNotGiven, ) - Conversation内部通过path_template(/conversations/{conversation_id}, ...)构造 URL 并发起GET请求conversations.py。值得注意的是源码在请求前对conversation_id做了空值校验if not conversation_id: raise ValueError(fExpected a non-empty value for conversation_id but received {conversation_id!r})因此传入空字符串或None会在本地立即抛出ValueError而不是发起到服务器的无效请求。4.2 update更新会话元数据client.conversations.update( conversation_id, *, metadata: Metadata, # 必填 extra_headersNone, extra_queryNone, extra_bodyNone, timeoutNotGiven, ) - Conversationupdate与create不同metadata是必填参数Required标记见 conversation_update_params.py且update只接受metadata一个业务字段不会修改会话内已有条目。请求以POST方法发送到/conversations/{conversation_id}请求体为{metadata: metadata}。4.3 delete删除会话client.conversations.delete( conversation_id, *, extra_headersNone, extra_queryNone, extra_bodyNone, timeoutNotGiven, ) - ConversationDeletedResource使用DELETE方法请求/conversations/{conversation_id}conversations.py。文档注释明确指出一个关键语义删除会话不会删除其中的条目Items——即条目对象独立于会话生命周期而存在。返回值为ConversationDeletedResource包含id、deleted布尔标志与object字段。五、Items 子资源会话内容的管理核心Items 是会话中的最小管理单位对应client.conversations.items方法实现见 items.py。5.1 create向会话添加条目client.conversations.items.create( conversation_id, *, items: Iterable[ResponseInputItemParam], # 必填一次最多 20 个 include: List[ResponseIncludable] | Omit omit, extra_headersNone, extra_queryNone, extra_bodyNone, timeoutNotGiven, ) - ConversationItemListitems为必填参数类型同样是ResponseInputItemParaminclude作为查询参数querymaybe_transform({include: include}, ...)而非请求体随请求发送用于请求额外的输出字段详见下文第六节返回类型为ConversationItemList——注意是“列表”而不是单个条目。测试中的最小调用见 test_items.pyitem client.conversations.items.create( conversation_idconv_123, items[ { content: string, role: user, type: message, } ], )5.2 retrieve获取单个条目client.conversations.items.retrieve( item_id, # 必填 *, conversation_id, # 必填关键字参数 include: List[ResponseIncludable] | Omit omit, ... ) - ConversationItemitem_id与conversation_id均为必填二者都通过path_template拼入 URL/conversations/{conversation_id}/items/{item_id}。源码中对两个 ID 分别做空值校验items.py。由于ConversationItem是联合类型源码中通过cast(Any, ConversationItem)绕过类型系统的限制来完成反序列化见 items.py并在注释中说明“Union types cannot be passed as arguments in the type system”。5.3 list分页列出会话条目client.conversations.items.list( conversation_id, *, after: str | Omit omit, include: List[ResponseIncludable] | Omit omit, limit: int | Omit omit, order: Literal[asc, desc] | Omit omit, ... ) - SyncConversationCursorPage[ConversationItem]四个查询参数定义见 item_list_params.pyafter游标分页参数传入一个条目 ID表示“列出该条目之后的数据”用于翻页limit返回数量上限范围1100默认20order排序方向默认desc降序asc表示升序include额外输出字段见第六节。list不走普通的_get而是调用self._get_api_list(...)使用SyncConversationCursorPage[ConversationItem]作为分页容器items.py。SyncConversationCursorPage是 SDK 的游标分页类型定义见 pagination.py支持自动翻页与手动游标遍历。异步版返回AsyncPaginator[ConversationItem, AsyncConversationCursorPage[ConversationItem]]。5.4 delete删除条目client.conversations.items.delete( item_id, *, conversation_id, ... ) - Conversation与删除整个会话不同删除条目返回的是Conversation即删除后的会话对象而不是ConversationDeletedResource。这与“删除会话不会删除条目”的语义形成了呼应条目的删除是会话内容管理的一部分删除后仍可通过返回的会话对象确认当前状态。六、include 参数请求额外的输出字段include是 items 的create、retrieve、list三个方法共有的可选参数类型为List[ResponseIncludable]用于要求响应中包含默认情况下不返回的附加数据。源码文档字符串items.py列出的当前支持值web_search_call.action.sources包含 Web Search 工具调用的来源code_interpreter_call.outputs包含代码解释器工具调用中 Python 代码执行的输出computer_call_output.output.image_url包含计算机调用输出的图片 URLfile_search_call.results包含文件搜索工具调用的搜索结果message.input_image.image_url包含输入消息中的图片 URLmessage.output_text.logprobs为 assistant 消息附带 logprobs 对数概率reasoning.encrypted_content包含推理 token 的加密版本使推理条目能在无状态场景如storefalse或组织启用零数据保留计划下用于多轮对话。测试中使用的示例test_items.pyitem client.conversations.items.create( conversation_idconv_123, items[{content: string, role: user, phase: commentary, type: message}], include[file_search_call.results], )注意include是随查询参数query string发送的而非 JSON 请求体这在实现上与items形成了区分。七、底层实现细节与高级用法7.1 统一的认证与路径模板机制所有 Conversations 端点均在make_request_options中声明security{bearer_auth: True}意味着这些请求使用客户端的 Bearer TokenAuthorization: Bearer API_KEY认证。URL 构造统一使用path_template工具来自 _utils以类型安全的方式将conversation_id、item_id注入路径模板避免字符串拼接错误。7.2 with_raw_response获取原始响应与 SDK 其他资源一致Conversations与Items都提供with_raw_response前缀用于获取包含 HTTP 头、状态码等原始信息而不直接解析 JSONconversations.pyresponse client.conversations.with_raw_response.create() assert response.is_closed is True conversation response.parse() # 手动解析with_streaming_response则是其“不急于读取响应体”的变体conversations.pywith client.conversations.with_streaming_response.create() as response: assert not response.is_closed conversation response.parse()对应测试见 test_conversations.py。异步版提供AsyncConversationsWithRawResponse、AsyncConversationsWithStreamingResponse等对称实现。7.3 方法级空值校验retrieve/update/delete 以及 items 的四个方法都内置了空值防护conversation_id或item_id为空时立即抛出带明确消息的ValueErrorconversations.py、items.py。这一设计让参数错误在本地尽早暴露而不是等到服务器返回 4xx。八、完整实战示例会话的全生命周期以下综合示例演示从创建会话到管理条目的完整流程结合 test_conversations.py 与 test_items.py 中的调用形态from openai import OpenAI client OpenAI() # 1. 创建会话携带初始条目与元数据 conversation client.conversations.create( items[ { type: message, role: user, content: [{type: input_text, text: 帮我分析这份代码}], } ], metadata{project: code-review, owner: alice}, ) conversation_id conversation.id # 2. 追加条目一次最多 20 条 result client.conversations.items.create( conversation_idconversation_id, items[ {type: message, role: user, content: [{type: input_text, text: 再看一下性能瓶颈}]} ], include[message.output_text.logprobs], ) # 3. 分页列出条目默认 desc最多 100 条 page client.conversations.items.list( conversation_idconversation_id, limit20, orderdesc, ) for item in page.data: print(item.id, item.type) # 4. 更新会话元数据 client.conversations.update( conversation_id, metadata{project: code-review, status: archived}, ) # 5. 删除单个条目返回更新后的会话 conversation client.conversations.items.delete( item_iditem_id, conversation_idconversation_id, ) # 6. 删除整个会话条目不会被删除 deleted client.conversations.delete(conversation_id) assert deleted.deleted is True如需并发场景可将OpenAI替换为AsyncOpenAI所有方法签名保持一致并加上await分页容器则相应变为AsyncConversationCursorPage。九、关键源码路径索引API 参考文档api.md资源实现conversations.py、items.py参数模型conversation_create_params.py、conversation_update_params.py、item_create_params.py、item_list_params.py、item_retrieve_params.py返回模型conversation.py、conversation_deleted_resource.py、message.py、conversation_item.py分页类型pagination.py测试用例test_conversations.py、test_items.py十、小结Conversations 资源为多轮、多模态、多工具会话提供了完整的管理能力create/retrieve/update/delete负责会话本体的生命周期items.create/retrieve/list/delete负责会话内容的细粒度管理并借助游标分页、include扩展字段、with_raw_response/with_streaming_response等机制满足从轻量调用到原始响应控制的各种需求。掌握这一资源体系你就能在应用中构建持久化的对话上下文为后续的 Responses API 多轮推理打下基础。赞分享人工智能大模型【免费下载链接】openai-pythonThe official Python library for the OpenAI API项目地址https://gitcode.com/GitHub_Trending/op/openai-python点击查看免费下载相关推荐如何用一条命令拿到全球逐小时天气预报Open-Meteo 免费天气 API 完全指南如何用一条命令拿到全球逐小时天气预报Open Meteo 免费天气 API 完全指南 想在 App 里放一张未来 16 天的逐小时温度曲线却要先注册账号、等后端API网关数据工程DataHub Tags API 实战指南通过 GraphQL 与 Python SDK 完成标签的增删改查DataHub Tags API 实战指南通过 GraphQL 与 Python SDK 完成标签的增删改查 Tags 是 DataHub 中一类非正式、松散数据目录数据治理数据血缘后端前端数据工程数据集成ToolJet Google Sheets 数据源接入与增删改查操作实战指南ToolJet Google Sheets 数据源接入与增删改查操作实战指南 本篇技术指南围绕 ToolJet 官方数据源文档 docs/docs/data s低代码后端前端AI 应用MCP 服务上一篇【免费下载】 Emby-unlocked解锁Emby Premiere特性的开源项目下一篇CANN/asc-devkit y1f函数文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考