本文详解在 openai 新版 python sdk（v1.0+）中，如何从 `embeddings.create()` 响应中准确提取嵌入向量，重点说明 `.data[0].embedding` 的访问方式及常见误区。
在 OpenAI 于 2023 年发布的 v1.x Python SDK 中，API 响应对象已全面重构为强类型 Pydantic 模型，不再返回传统字典（dict）结构。这意味着你不能再使用 response['data'][0]['embedding'] 这类字典式键访问——这正是旧版代码（如早期 GitHub Gist 示例）在新版 SDK 中失效的根本原因。
正确做法是通过属性链式访问获取嵌入向量：
from openai import OpenAI
client = OpenAI(api_key="sk-...") # 替换为你的实际 API key
def get_embedding(text: str, client: OpenAI) -> list[float]:
response = client.embeddings.create(
model="text-embedding-ada-002", # 注意：该模型已逐步弃用，推荐使用 "text-embedding-3-small" 或 "text-embedding-3-large"
input=[text]
)
return response.data[0].embedding # ✅ 正确：访问 Embedding 对象的 embedding 属性
# 使用示例
text = "Hello, world!"
vector = get_embedding(text, client)
print(f"Embedding dimension: {len(vector)}") # 通常为 1536（ada-002）或 256/1024/3072（新模型）
print(f"First 5 values: {vector[:5]}")⚠️ 关键注意事项：
- response.data 是一个 list[Embedding]，即使只传入单个文本（input=[text]），也必须通过索引 [0] 获取首个元素；
- response.data[0].embedding 是 list[float] 类型，可直接用于余弦相似度计算、FAISS 索引构建等下游任务；
- 若输入多个文本（如 input=["a", "b", "c"]），response.data 长度将为 3，需遍历 response.data[i].embedding 分别提取；
- text-embedding-ada-002 已被标记为 legacy，官方推荐迁移至 text-embedding-3-small（更优性价比）或 text-embedding-3-large（更高精度），二者支持维度裁剪（dimensions 参数）和更强的语义表征能力。
✅ 最佳实践建议：
始终检查响应结构（print(type(response)) 和 print(response.model_dump())），避免假设响应格式；对生产环境，建议添加异常处理与长度校验：
if not response.data or len(response.data) == 0:
raise ValueError("No embedding returned by API")
embedding = response.data[0].embedding
assert isinstance(embedding, list), "Embedding must be a list of floats"掌握这一访问模式，是构建 RAG、语义搜索、聚类分析等 AI 应用的基础前提。
