Login
Back to Blog
Text-Embedding-3-Small API 튜토리얼 - OpenAI 임베딩 모델 가이드

Text-Embedding-3-Small API 튜토리얼 - OpenAI 임베딩 모델 가이드

C
Crazyrouter Team
January 26, 2026
31 views한국어Tutorial
Share:

의미 기반 검색 엔진 또는 RAG(Retrieval-Augmented Generation) 시스템을 구축하고 있나요? Text-embedding-3-small은 텍스트를 숫자 벡터로 변환해 강력한 유사도 검색과 콘텐츠 검색을 가능하게 하는 OpenAI의 최신 임베딩 모델입니다.

이 가이드에서 다루는 내용:

  • 텍스트 임베딩이 무엇이며 왜 중요한지
  • text-embedding-3-small API 사용 방법
  • Python 및 Node.js 전체 코드 예제
  • 저장소 최적화를 위한 커스텀 차원 설정
  • 가격 비교 및 비용 최적화 전략

What is Text-Embedding-3-Small?#

Text-embedding-3-small은 2024년 1월에 공개된 OpenAI의 소형 임베딩 모델입니다. 텍스트를 의미를 담은 1536차원 벡터로 변환하며, 이를 통해 다음과 같은 작업이 가능합니다:

  • Semantic Search: 키워드가 아닌 의미를 기반으로 관련 문서 찾기
  • RAG Systems: LLM 응답을 위한 컨텍스트 검색
  • Similarity Matching: 추천을 위한 텍스트 유사도 비교
  • Clustering: 유사한 문서들을 그룹화
  • Classification: 내용 기반 텍스트 분류

Model Specifications#

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

Quick Start#

Prerequisites#

  1. Crazyrouter에 회원 가입
  2. 대시보드에서 API 키 발급
  3. Python 3.8+ 또는 Node.js 16+

Python Example#

python
from openai import OpenAI

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

# Generate embedding for a single text
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 Example#

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 Example#

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"
  }'

Response:

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"
)

# Batch embedding - multiple texts at once
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
)

# Access each embedding
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
# Use 512 dimensions instead of 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

Dimension Comparison#

DimensionsStorage (per vector)Use Case
2561 KB모바일 앱, 제한된 저장 공간
5122 KB성능과 비용의 균형
10244 KB높은 정확도가 필요한 경우
15366 KB최대 정확도 필요 시

Building a Semantic Search System#

다음은 의미 기반 검색 시스템을 구축하는 전체 예제입니다:

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))

# Document database
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"
]

# Pre-compute embeddings for all documents
doc_embeddings = [get_embedding(doc) for doc in documents]

# Search function
def search(query, top_k=3):
    query_embedding = get_embedding(query)

    # Calculate similarities
    similarities = [
        cosine_similarity(query_embedding, doc_emb)
        for doc_emb in doc_embeddings
    ]

    # Get top results
    results = sorted(
        zip(documents, similarities),
        key=lambda x: x[1],
        reverse=True
    )[:top_k]

    return results

# Example search
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

Integration with Vector Databases#

Pinecone Integration#

python
import pinecone
from openai import OpenAI

# Initialize clients
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 Integration#

python
import chromadb
from openai import OpenAI

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

# Initialize 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]

# Add documents
documents = ["doc1 content", "doc2 content", "doc3 content"]
embeddings = get_embeddings(documents)

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

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

Available Embedding Models#

Crazyrouter는 여러 OpenAI 임베딩 모델에 대한 액세스를 제공합니다:

ModelDimensionsPrice RatioBest For
text-embedding-3-small15360.01일반적인 용도, 최고의 가성비
text-embedding-3-large30720.065높은 정밀도가 필요한 경우
text-embedding-ada-00215360.05레거시 호환성

Pricing Comparison#

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

Pricing Disclaimer: 표의 가격은 예시용이며 변경될 수 있습니다. 실제 청구는 요청 시점의 실시간 가격을 기준으로 합니다.

Cost Savings Example:

10M tokens/월을 처리하는 RAG 시스템의 경우:

  • OpenAI Official: $200/월
  • Crazyrouter: $20/월
  • 절감율: 90%

Best Practices#

1. Batch Your Requests#

python
# Good - single API call for multiple texts
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["text1", "text2", "text3"]  # Up to 2048 texts
)

# Bad - multiple API calls
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):
    # Create cache key
    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 dimensions: 모바일 앱, IoT 디바이스
  • 512 dimensions: 저장 공간 제약이 있는 웹 애플리케이션
  • 1024 dimensions: 일반적인 애플리케이션
  • 1536 dimensions: 최대 정확도가 필요한 경우

Frequently Asked Questions#

What's the difference between text-embedding-3-small and text-embedding-3-large?#

Text-embedding-3-small은 1536차원 벡터를 생성하며 비용 효율성에 최적화되어 있습니다. Text-embedding-3-large는 3072차원 벡터를 생성하며 더 높은 정확도를 제공하지만 비용은 약 6.5배 높습니다. 대부분의 애플리케이션에서는 text-embedding-3-small로도 훌륭한 결과를 얻을 수 있습니다.

Can I reduce dimensions after generating embeddings?#

네, dimensions 파라미터를 사용하여 처음부터 더 작은 차원의 벡터를 생성할 수 있습니다. 전체 차원의 벡터를 만든 뒤 잘라내는 것보다 훨씬 효율적입니다.

How many texts can I embed in one request?#

한 번의 API 요청으로 최대 2048개의 텍스트를 임베딩할 수 있습니다. 대규모 데이터셋의 경우, 2048개 단위로 요청을 배치 처리하는 것이 좋습니다.

Are the embeddings normalized?#

네, text-embedding-3-small은 정규화된(단위 길이) 벡터를 반환하므로, 더 빠른 계산을 위해 cosine similarity 대신 dot product를 바로 사용할 수 있습니다.

Getting Started#

  1. Crazyrouter회원 가입
  2. 대시보드에서 API 키 발급
  3. SDK 설치: pip install openai 또는 npm install openai
  4. 위의 코드 예제를 참고해 임베딩 생성 시작

Related Articles:

문의: support@crazyrouter.com

Related Articles