CrazyrouterCrazyrouter
Login
Back to Blog
Text-Embedding-3-Small API 教程 - OpenAI 向量嵌入模型指南

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

C
Crazyrouter Team
January 26, 2026
39 views中文Tutorial
Share:

正在构建语义搜索引擎或 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）：根据内容对文本进行类别划分

模型规格#

SpecificationValue
Model Nametext-embedding-3-small
Default Dimensions1536
Custom Dimensions256, 512, 1024, 1536
Max Input Tokens8,191
OutputNormalized vector

快速上手#

前置条件#

  1. 在 Crazyrouter 注册账号
  2. 在控制台获取你的 API Key
  3. 准备好 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

维度对比#

DimensionsStorage (per vector)Use Case
2561 KB移动应用、存储受限场景
5122 KB性能与成本的平衡选择
10244 KB对精度要求较高的应用
15366 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 向量嵌入模型的访问能力：

ModelDimensionsPrice RatioBest For
text-embedding-3-small15360.01通用场景，性价比最高
text-embedding-3-large30720.065精度要求极高的场景
text-embedding-ada-00215360.05旧系统兼容需求

价格对比#

ProviderModelPrice per 1M tokens
OpenAI Officialtext-embedding-3-small$0.020
Crazyroutertext-embedding-3-small$0.002
OpenAI Officialtext-embedding-3-large$0.130
Crazyroutertext-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 返回的是单位长度的归一化向量，因此你可以直接使用点积来代替余弦相似度，获得更快的计算速度。

开始使用#

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

相关文章：

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

Available in other languages:

العربيةDanskDeutschEnglishEspañolFrançaisBahasa IndonesiaItaliano日本語Қазақша한국어Bahasa MelayuNederlandsNorskPolskiPortuguêsРусскийไทยTürkçeTiếng Việt

Related Articles

Claude Code 安装与使用指南 - AI 编程助手配置教程Tutorial

Claude Code 安装与使用指南 - AI 编程助手配置教程

完整指南，教你如何安装和配置 Claude Code 这一 AI 编程助手。学习如何安装 Node.js、配置 API Token，并在终端中开始与你的 AI 一起编程。

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

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

"Gemini CLI 完整使用教程，从安装配置到高级用法。学会用 Google 的命令行 AI 工具提升开发效率，包含实用示例和技巧。"

Feb 19
Gemini CLI 用户指南 - 在终端中使用 Google AITutorial

Gemini CLI 用户指南 - 在终端中使用 Google AI

完整指南讲解如何安装和配置 Gemini CLI，这是一款由 Google 提供的开源命令行 AI 工具。学习如何配置代理、使用内置工具，并通过 Gemini 2.5 Pro 实现工作流自动化。

Jan 24