2.0.0 (2025-09-30)

2.0.0 (2025-09-30)

【免费下载链接】openai-python The official Python library for the OpenAI API 项目地址: https://gitcode.com/GitHub_Trending/op/openai-python

⚠ BREAKING CHANGES

• api: ResponseFunctionToolCallOutputItem.output and ResponseCustomToolCallOutput.output now return string | Array<ResponseInputText | ResponseInputImage | ResponseInputFile> instead of string only. This may break existing callsites that assume output is always a string.

Features

• api: Support images and files for function call outputs in responses, BatchUsage

虽然变更日志未直接提及Embedding接口变化，但通过分析类型定义文件可以发现，Embedding相关的数据结构已重构。新的[src/openai/types/embedding.py](https://link.gitcode.com/i/8acb8a6cc72f8915834f06271f47c100)定义如下：

```python
class Embedding(BaseModel):
    embedding: List[float]
    """The embedding vector, which is a list of floats.
    
    The length of vector depends on the model as listed in the
    [embedding guide](https://platform.openai.com/docs/guides/embeddings).
    """
    
    index: int
    """The index of the embedding in the list of embeddings."""
    
    object: Literal["embedding"]
    """The object type, which is always "embedding"."""

这一变更主要影响：

• 直接使用Embedding类的代码
• 依赖旧有响应结构的类型注解
• 响应结果解析逻辑

核心变更解析

数据结构变化

v2.0.0版本中，Embedding响应的核心结构保持不变，但引入了更严格的类型检查和注解。主要变化包括：

变更点	旧版本	新版本
基类	Dict	BaseModel
类型注解	基础类型	Literal等高级类型
文档字符串	简略	详细说明

接口调用方式

虽然Embedding接口的调用方式未发生明显变化，但响应处理需要适应新的数据结构：

旧版本代码示例：

import openai

response = openai.Embedding.create(
    model="text-embedding-ada-002",
    input="The food was delicious and the waiter..."
)

# 直接通过字典访问
embedding_vector = response['data'][0]['embedding']

新版本代码示例：

import openai
from openai.types import Embedding

response = openai.Embedding.create(
    model="text-embedding-ada-002",
    input="The food was delicious and the waiter..."
)

# 通过模型对象访问
embedding_vector = response.data[0].embedding

迁移步骤与最佳实践

1. 检查版本兼容性

首先确认你正在使用的OpenAI-Python库版本：

pip show openai | grep Version

如果版本≥2.0.0，需要进行以下迁移。

2. 更新导入语句

根据新的类型定义，更新导入语句：

# 旧版本
from openai import Embedding

# 新版本
from openai.types import Embedding

3. 修改响应处理逻辑

将字典访问方式改为对象属性访问：

# 旧版本
embedding = response['data'][0]['embedding']
index = response['data'][0]['index']

# 新版本
embedding = response.data[0].embedding
index = response.data[0].index

4. 类型注解升级

更新函数参数和返回值的类型注解：

# 旧版本
def process_embedding(embedding_data: dict) -> list[float]:
    return embedding_data['embedding']

# 新版本
from openai.types import Embedding

def process_embedding(embedding_data: Embedding) -> list[float]:
    return embedding_data.embedding

常见问题与解决方案

Q: 升级后出现AttributeError: 'dict' object has no attribute 'data'

A: 这是由于仍在使用旧版本的响应处理方式。请确保将所有response['data']替换为response.data。

Q: 类型检查工具提示Module 'openai' has no attribute 'Embedding'

A: 这是因为Embedding类型已移至openai.types子模块。请更新导入语句为from openai.types import Embedding。

Q: 如何处理批量嵌入请求的响应？

A: 批量请求的处理方式类似，response.data将包含一个Embedding对象列表：

response = openai.Embedding.create(
    model="text-embedding-ada-002",
    input=[
        "First text to embed",
        "Second text to embed"
    ]
)

# 获取所有嵌入向量
embeddings = [item.embedding for item in response.data]

【免费下载链接】openai-python The official Python library for the OpenAI API 项目地址: https://gitcode.com/GitHub_Trending/op/openai-python