Text-Embedding-3-Small API 教程 - OpenAI 向量嵌入模型指南

正在构建语义搜索引擎或 RAG（Retrieval-Augmented Generation，检索增强生成）系统？Text-embedding-3-small 是 OpenAI 最新的向量嵌入模型，可以将文本转换为数值向量，从而实现强大的相似度搜索和内容检索能力。

在本指南中，你将学到：

什么是文本向量嵌入，以及它为何重要
如何使用 text-embedding-3-small API
完整的 Python 和 Node.js 代码示例
自定义向量维度以优化存储
价格对比与成本优化策略

什么是 Text-Embedding-3-Small？#

Text-embedding-3-small 是 OpenAI 于 2024 年 1 月发布的紧凑型向量嵌入模型。它可以将文本转换为 1536 维向量，捕捉语义信息，从而实现：

语义搜索（Semantic Search）：基于“含义”而不仅仅是关键词来查找相关文档
RAG 系统：为大语言模型（LLM）的回答检索和提供上下文
相似度匹配（Similarity Matching）：比较文本相似度，用于推荐等场景
聚类（Clustering）：将相似文档分为同一组
分类（Classification）：根据内容对文本进行类别划分

模型规格#

Specification	Value
Model Name	`text-embedding-3-small`
Default Dimensions	1536
Custom Dimensions	256, 512, 1024, 1536
Max Input Tokens	8,191
Output	Normalized vector

快速上手#

前置条件#

在 Crazyrouter 注册账号
在控制台获取你的 API Key
准备好 Python 3.8+ 或 Node.js 16+

Python 示例#

python

from openai import OpenAI

client = OpenAI(
    api_key="your-crazyrouter-api-key",
    base_url="https://crazyrouter.com/v1"
)

# 为单条文本生成向量
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Machine learning is transforming industries worldwide."
)

embedding = response.data[0].embedding
print(f"Dimensions: {len(embedding)}")  # Output: 1536
print(f"First 5 values: {embedding[:5]}")

Node.js 示例#

javascript

import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'your-crazyrouter-api-key',
    baseURL: 'https://crazyrouter.com/v1'
});

async function getEmbedding(text) {
    const response = await client.embeddings.create({
        model: 'text-embedding-3-small',
        input: text
    });

    return response.data[0].embedding;
}

// Usage
const embedding = await getEmbedding('Machine learning is amazing');
console.log(`Dimensions: ${embedding.length}`);  // Output: 1536

cURL 示例#

bash

curl -X POST https://crazyrouter.com/v1/embeddings \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "Hello world"
  }'

响应示例：

json

{
  "object": "list",
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  },
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [-0.0020785425, -0.049085874, 0.02094679, ...]
    }
  ]
}

批量向量嵌入（Batch Embedding）#

在一次 API 调用中处理多条文本，以提高效率：

python

from openai import OpenAI

client = OpenAI(
    api_key="your-crazyrouter-api-key",
    base_url="https://crazyrouter.com/v1"
)

# 批量生成向量 - 一次处理多条文本
texts = [
    "Python is a programming language",
    "JavaScript runs in browsers",
    "Machine learning uses neural networks"
]

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=texts
)

# 访问每一条向量
for i, data in enumerate(response.data):
    print(f"Text {i}: {len(data.embedding)} dimensions")

# Output:
# Text 0: 1536 dimensions
# Text 1: 1536 dimensions
# Text 2: 1536 dimensions

自定义向量维度（Custom Dimensions）#

通过减小向量维度来降低存储成本。该模型支持在保持较高质量的前提下进行维度压缩：

python

# 使用 512 维向量替代默认的 1536 维
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Your text here",
    dimensions=512  # Options: 256, 512, 1024, 1536
)

embedding = response.data[0].embedding
print(f"Dimensions: {len(embedding)}")  # Output: 512

维度对比#

Dimensions	Storage (per vector)	Use Case
256	1 KB	移动应用、存储受限场景
512	2 KB	性能与成本的平衡选择
1024	4 KB	对精度要求较高的应用
1536	6 KB	追求最高精度的场景

构建语义搜索系统#

下面是一个构建语义搜索系统的完整示例：

python

import numpy as np
from openai import OpenAI

client = OpenAI(
    api_key="your-crazyrouter-api-key",
    base_url="https://crazyrouter.com/v1"
)

def get_embedding(text):
    """Get embedding for a single text"""
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )
    return response.data[0].embedding

def cosine_similarity(a, b):
    """Calculate cosine similarity between two vectors"""
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# 文档库
documents = [
    "Python is great for data science and machine learning",
    "JavaScript is essential for web development",
    "Docker containers simplify deployment",
    "Kubernetes orchestrates container workloads",
    "PostgreSQL is a powerful relational database"
]

# 为所有文档预先计算向量
doc_embeddings = [get_embedding(doc) for doc in documents]

# 搜索函数
def search(query, top_k=3):
    query_embedding = get_embedding(query)

    # 计算相似度
    similarities = [
        cosine_similarity(query_embedding, doc_emb)
        for doc_emb in doc_embeddings
    ]

    # 获取 Top 结果
    results = sorted(
        zip(documents, similarities),
        key=lambda x: x[1],
        reverse=True
    )[:top_k]

    return results

# 示例搜索
results = search("How to deploy applications?")
for doc, score in results:
    print(f"Score: {score:.4f} - {doc}")

# Output:
# Score: 0.8234 - Docker containers simplify deployment
# Score: 0.7891 - Kubernetes orchestrates container workloads
# Score: 0.6543 - PostgreSQL is a powerful relational database

与向量数据库集成#

Pinecone 集成#

python

import pinecone
from openai import OpenAI

# 初始化客户端
client = OpenAI(
    api_key="your-crazyrouter-api-key",
    base_url="https://crazyrouter.com/v1"
)

pinecone.init(api_key="your-pinecone-key")
index = pinecone.Index("your-index")

def embed_and_upsert(texts, ids):
    """Embed texts and store in Pinecone"""
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )

    vectors = [
        (id, data.embedding)
        for id, data in zip(ids, response.data)
    ]

    index.upsert(vectors=vectors)

def search_pinecone(query, top_k=5):
    """Search Pinecone with query embedding"""
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=query
    )

    results = index.query(
        vector=response.data[0].embedding,
        top_k=top_k
    )

    return results

ChromaDB 集成#

python

import chromadb
from openai import OpenAI

client = OpenAI(
    api_key="your-crazyrouter-api-key",
    base_url="https://crazyrouter.com/v1"
)

# 初始化 ChromaDB
chroma_client = chromadb.Client()
collection = chroma_client.create_collection("documents")

def get_embeddings(texts):
    """Get embeddings for multiple texts"""
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )
    return [data.embedding for data in response.data]

# 添加文档
documents = ["doc1 content", "doc2 content", "doc3 content"]
embeddings = get_embeddings(documents)

collection.add(
    embeddings=embeddings,
    documents=documents,
    ids=["doc1", "doc2", "doc3"]
)

# 查询
query_embedding = get_embeddings(["search query"])[0]
results = collection.query(
    query_embeddings=[query_embedding],
    n_results=3
)

可用的向量嵌入模型#

Crazyrouter 提供多个 OpenAI 向量嵌入模型的访问能力：

Model	Dimensions	Price Ratio	Best For
`text-embedding-3-small`	1536	0.01	通用场景，性价比最高
`text-embedding-3-large`	3072	0.065	精度要求极高的场景
`text-embedding-ada-002`	1536	0.05	旧系统兼容需求

价格对比#

Provider	Model	Price per 1M tokens
OpenAI Official	text-embedding-3-small	$0.020
Crazyrouter	text-embedding-3-small	$0.002
OpenAI Official	text-embedding-3-large	$0.130
Crazyrouter	text-embedding-3-large	$0.013

价格声明：以上价格仅为演示示例，可能随时间变化。实际计费以请求时的实时价格为准。

成本节省示例：

对于一个每月处理 10M tokens 的 RAG 系统：

OpenAI Official：$200/月
Crazyrouter：$20/月
节省：90%

最佳实践#

1. 批量请求（Batch Your Requests）#

python

# 推荐写法 - 一次 API 调用处理多条文本
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["text1", "text2", "text3"]  # 一次最多 2048 条
)

# 不推荐 - 多次 API 调用
for text in texts:
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )

2. 缓存向量结果（Cache Embeddings）#

python

import hashlib
import json

embedding_cache = {}

def get_embedding_cached(text):
    # 为文本创建缓存键
    cache_key = hashlib.md5(text.encode()).hexdigest()

    if cache_key in embedding_cache:
        return embedding_cache[cache_key]

    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )

    embedding = response.data[0].embedding
    embedding_cache[cache_key] = embedding

    return embedding

3. 使用合适的维度（Use Appropriate Dimensions）#

256 维：移动应用、IoT 设备等资源极其受限场景
512 维：有一定存储约束的 Web 应用
1024 维：大多数标准应用场景
1536 维：对准确率要求最高的任务

常见问题（FAQ）#

text-embedding-3-small 和 text-embedding-3-large 有什么区别？#

Text-embedding-3-small 生成 1536 维向量，重点优化成本与性能的平衡。Text-embedding-3-large 生成 3072 维向量，精度更高，但成本约为前者的 6.5 倍。对于大多数应用场景，text-embedding-3-small 已能提供非常优秀的效果。

我可以在生成向量后再降维吗？#

可以，但更推荐直接使用 dimensions 参数生成较小维度的向量。相比先生成完整向量再手动截断或降维，直接指定维度会更加高效且更合理。

一次请求最多可以嵌入多少条文本？#

你可以在一次 API 请求中嵌入最多 2048 条文本。对于大规模数据集，请按最多 2048 条一批进行分批处理。

返回的向量是归一化的吗？#

是的，text-embedding-3-small 返回的是单位长度的归一化向量，因此你可以直接使用点积来代替余弦相似度，获得更快的计算速度。

开始使用#

注册账号：前往 Crazyrouter
获取 API Key：在控制台中创建并复制你的密钥
安装 SDK：pip install openai 或 npm install openai
参考上述示例代码，开始为你的应用生成向量嵌入

相关文章：

如有问题，请联系：support@crazyrouter.com

Text-Embedding-3-Small API 教程 - OpenAI 向量嵌入模型指南

什么是 Text-Embedding-3-Small？#

模型规格#

快速上手#

前置条件#

Python 示例#

Node.js 示例#

cURL 示例#

批量向量嵌入（Batch Embedding）#

自定义向量维度（Custom Dimensions）#

维度对比#

构建语义搜索系统#

与向量数据库集成#

Pinecone 集成#

ChromaDB 集成#

可用的向量嵌入模型#

价格对比#

最佳实践#

1. 批量请求（Batch Your Requests）#

2. 缓存向量结果（Cache Embeddings）#

3. 使用合适的维度（Use Appropriate Dimensions）#

常见问题（FAQ）#

text-embedding-3-small 和 text-embedding-3-large 有什么区别？#

我可以在生成向量后再降维吗？#

一次请求最多可以嵌入多少条文本？#

返回的向量是归一化的吗？#

开始使用#

Related Articles

"Gemini CLI 使用教程：Google 命令行 AI 助手完全指南"

Doubao Seed Code：字节跳动 AI 代码生成模型 - 完整 API 指南

"Claude是什么？Anthropic AI助手完整指南"