
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 は、2024 年 1 月にリリースされた OpenAI のコンパクトな埋め込みモデルです。テキストを 1536 次元のベクトルに変換し、意味的な情報を捉えることで、以下を実現します:
- セマンティック検索: キーワードだけでなく「意味」に基づいて関連文書を検索
- RAG システム: LLM の応答に必要なコンテキストを検索・取得
- 類似度マッチング: レコメンデーションのためにテキストの類似度を比較
- クラスタリング: 類似した文書をグルーピング
- 分類: コンテンツに基づいてテキストをカテゴリ分け
モデル仕様#
| 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 キーを取得
- Python 3.8+ または Node.js 16+ を用意
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 例#
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 例#
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"
}'
レスポンス:
{
"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, ...]
}
]
}
バッチ埋め込み#
複数テキストを 1 回の API 呼び出しで処理して効率を高めます:
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
カスタム次元#
より小さい次元数を使うことでストレージコストを削減できます。このモデルは、品質を保ちながら次元削減をサポートします:
# 1536 の代わりに 512 次元を使用
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 | 最高精度が求められる用途 |
セマンティック検索システムの構築#
以下は、セマンティック検索システムを構築する完全な例です:
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
]
# 上位結果を取得
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 との連携#
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 との連携#
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 トークン/月を処理する RAG システムの場合:
- OpenAI Official: $200/月
- Crazyrouter: $20/月
- 削減率: 90%
ベストプラクティス#
1. リクエストをバッチ処理する#
# Good - 複数テキストを 1 回の API 呼び出しで処理
response = client.embeddings.create(
model="text-embedding-3-small",
input=["text1", "text2", "text3"] # 最大 2048 テキスト
)
# Bad - テキストごとに複数回 API を呼び出す
for text in texts:
response = client.embeddings.create(
model="text-embedding-3-small",
input=text
)
2. 埋め込みをキャッシュする#
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. 適切な次元数を選ぶ#
- 256 次元: モバイルアプリ、IoT デバイス
- 512 次元: ストレージ制約のある Web アプリケーション
- 1024 次元: 標準的なアプリケーション
- 1536 次元: 最高精度が求められる要件
よくある質問#
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 パラメータを使用することで、最初から小さい次元のベクトルを生成できます。フルサイズのベクトルを生成してから切り捨てるよりも効率的です。
1 回のリクエストで何件まで埋め込みできますか?#
1 回の API リクエストで最大 2048 件のテキストを埋め込みできます。大規模データセットの場合は、2048 件ずつのバッチに分けて処理してください。
埋め込みは正規化されていますか?#
はい、text-embedding-3-small は正規化済みベクトル(単位長)を返すため、より高速な計算のために cosine similarity の代わりに内積(dot product)を使用できます。
はじめ方#
- Crazyrouter に サインアップ
- ダッシュボードから API キーを取得
- SDK をインストール:
pip install openaiまたはnpm install openai - 上記のコード例を参考に 埋め込みを開始
関連記事:
お問い合わせは support@crazyrouter.com まで


