Embeddings

Embeddings is a technology that converts text into high-dimensional vectors, commonly used for semantic search, RAG (Retrieval-Augmented Generation), text classification, and similarity computation. RouteAPI provides a standard OpenAI-compatible Embeddings interface, supporting multiple embedding models.

Endpoint

POST /v1/embeddings

Full URL:

https://api.routeapi.ai/v1/embeddings

Use Cases

Scenario	Description
Semantic Search	Convert documents and queries into vectors, retrieve relevant content through similarity
RAG	Retrieve relevant document fragments as context to enhance LLM generation quality
Text Classification	Vectorize text for clustering or classification tasks
Recommendation Systems	Calculate text similarity for content recommendations
Deduplication	Identify duplicate or similar content through vector similarity

Request Examples

Single Text

curl https://api.routeapi.ai/v1/embeddings \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "RouteAPI 是一个统一的 AI API 网关"
  }'

Batch Text

curl https://api.routeapi.ai/v1/embeddings \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": [
      "第一段文本",
      "第二段文本",
      "第三段文本"
    ]
  }'

Request Parameters

Field	Type	Required	Description
model	string	Yes	Embedding model ID
input	string/array	Yes	Single text string or text array
encoding_format	string	No	Vector encoding format, float or base64, default float
dimensions	number	No	Returned vector dimensions (supported by some models), used for dimensionality reduction
user	string	No	End-user identifier for tracking and abuse monitoring

Response Example

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0023064255,
        -0.009327292,
        0.015797347,
        ...
      ]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

Response Fields

Field	Description
object	Fixed as list
data	Array of embedding results
data[].embedding	Array of floating-point vectors
data[].index	Index position of input text
model	Actual model ID used
usage.prompt_tokens	Number of tokens consumed by input
usage.total_tokens	Total number of tokens

Supported Embedding Models

OpenAI Models

Model ID	Default Dimensions	Performance	Use Cases
text-embedding-3-small	1536	Cost-effective	General semantic search, RAG
text-embedding-3-large	3072	High precision	Complex semantic tasks
text-embedding-ada-002	1536	Stable classic	Backward compatibility

Google Models

Model ID	Default Dimensions	Description
text-embedding-004	768	Google’s latest embedding model
gemini-embedding-001	768	Gemini series embedding model

Other Providers

Model ID	Default Dimensions	Provider
text-embedding-v1	1024	Baidu Wenxin
embedding-bert-512-v1	512	Zhipu AI
bge-large-zh	1024	BAAI BGE (Chinese)
bge-large-en	1024	BAAI BGE (English)

Model availability is subject to the console model list, different accounts may have different available models.

Batch Processing

Batch Size Limits

• The maximum number of texts processed in a single request depends on the specific model and service configuration.
• It is recommended not to exceed 100 texts per request.
• The token count of a single text should generally not exceed the model’s maximum input limit (usually 8192 tokens).

Batch Optimization Tips

1. Merge requests: Combine multiple short texts into one request to reduce network round trips.
2. Concurrency control: Large batches can be split and processed concurrently, recommended concurrency is no more than 5.
3. Error handling: When one text in a batch fails, the entire request may fail, proper retry and error handling is needed.

Code Examples

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

# Single text
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="RouteAPI 是一个统一的 AI API 网关"
)
embedding = response.data[0].embedding
print(f"向量维度: {len(embedding)}")
print(f"前 5 个值: {embedding[:5]}")

# Batch text
texts = [
    "人工智能正在改变世界",
    "机器学习是 AI 的核心技术",
    "深度学习推动了 AI 的发展"
]
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=texts
)
for i, data in enumerate(response.data):
    print(f"文本 {i}: 维度 {len(data.embedding)}")

Node.js (OpenAI SDK)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-routeapi-token',
  baseURL: 'https://api.routeapi.ai/v1'
});

async function getEmbedding() {
  // Single text
  const response = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: 'RouteAPI 是一个统一的 AI API 网关'
  });

  const embedding = response.data[0].embedding;
  console.log(`向量维度: ${embedding.length}`);
  console.log(`前 5 个值: ${embedding.slice(0, 5)}`);

  // Batch text
  const texts = [
    '人工智能正在改变世界',
    '机器学习是 AI 的核心技术',
    '深度学习推动了 AI 的发展'
  ];

  const batchResponse = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: texts
  });

  batchResponse.data.forEach((item, i) => {
    console.log(`文本 ${i}: 维度 ${item.embedding.length}`);
  });
}

getEmbedding();

curl

curl https://api.routeapi.ai/v1/embeddings \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["文本1", "文本2", "文本3"]
  }'

Semantic Similarity Computation

Python (Using NumPy)

import numpy as np
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

def cosine_similarity(vec1, vec2):
    """Calculate cosine similarity"""
    return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))

# Get embeddings for two texts
texts = [
    "RouteAPI 是一个 AI API 网关",
    "RouteAPI 提供统一的模型接入服务",
    "今天天气很好"
]

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

embeddings = [data.embedding for data in response.data]

# Calculate similarity
sim_0_1 = cosine_similarity(embeddings[0], embeddings[1])
sim_0_2 = cosine_similarity(embeddings[0], embeddings[2])

print(f"文本0 和 文本1 的相似度: {sim_0_1:.4f}")  # High similarity
print(f"文本0 和 文本2 的相似度: {sim_0_2:.4f}")  # Low similarity

Node.js (Using Math Library)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-routeapi-token',
  baseURL: 'https://api.routeapi.ai/v1'
});

function cosineSimilarity(vec1, vec2) {
  const dotProduct = vec1.reduce((sum, val, i) => sum + val * vec2[i], 0);
  const mag1 = Math.sqrt(vec1.reduce((sum, val) => sum + val * val, 0));
  const mag2 = Math.sqrt(vec2.reduce((sum, val) => sum + val * val, 0));
  return dotProduct / (mag1 * mag2);
}

async function computeSimilarity() {
  const texts = [
    'RouteAPI 是一个 AI API 网关',
    'RouteAPI 提供统一的模型接入服务',
    '今天天气很好'
  ];

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

  const embeddings = response.data.map(d => d.embedding);

  const sim_0_1 = cosineSimilarity(embeddings[0], embeddings[1]);
  const sim_0_2 = cosineSimilarity(embeddings[0], embeddings[2]);

  console.log(`文本0 和 文本1 的相似度: ${sim_0_1.toFixed(4)}`);
  console.log(`文本0 和 文本2 的相似度: ${sim_0_2.toFixed(4)}`);
}

computeSimilarity();

Vector Database Integration

Pinecone Example

from openai import OpenAI
import pinecone

# Initialize RouteAPI client
client = OpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

# Initialize Pinecone
pinecone.init(api_key="your-pinecone-key", environment="your-env")
index = pinecone.Index("your-index-name")

# Generate embeddings and store
documents = [
    {"id": "doc1", "text": "RouteAPI 是一个 AI API 网关"},
    {"id": "doc2", "text": "支持多家 AI 模型供应商"},
    {"id": "doc3", "text": "提供统一的接口和计费"}
]

for doc in documents:
    # Generate embedding
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=doc["text"]
    )
    embedding = response.data[0].embedding

    # Store to Pinecone
    index.upsert([(doc["id"], embedding, {"text": doc["text"]})])

# Query
query = "什么是 RouteAPI"
query_response = client.embeddings.create(
    model="text-embedding-3-small",
    input=query
)
query_embedding = query_response.data[0].embedding

# Search similar documents
results = index.query(query_embedding, top_k=3, include_metadata=True)
for match in results["matches"]:
    print(f"相似度: {match['score']:.4f}, 文本: {match['metadata']['text']}")

Weaviate Example

import weaviate
from openai import OpenAI

# Initialize RouteAPI client
client = OpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

# Connect Weaviate
weaviate_client = weaviate.Client("http://localhost:8080")

# Create schema (if not exists)
schema = {
    "class": "Document",
    "vectorizer": "none",  # We provide vectors ourselves
    "properties": [
        {"name": "text", "dataType": ["text"]}
    ]
}

# Insert documents
documents = [
    "RouteAPI 是一个 AI API 网关",
    "支持多家 AI 模型供应商",
    "提供统一的接口和计费"
]

for doc_text in documents:
    # Generate embedding
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=doc_text
    )
    embedding = response.data[0].embedding

    # Store to Weaviate
    weaviate_client.data_object.create(
        data_object={"text": doc_text},
        class_name="Document",
        vector=embedding
    )

# Query
query = "什么是 RouteAPI"
query_response = client.embeddings.create(
    model="text-embedding-3-small",
    input=query
)
query_embedding = query_response.data[0].embedding

# Vector search
results = weaviate_client.query.get("Document", ["text"]) \
    .with_near_vector({"vector": query_embedding}) \
    .with_limit(3) \
    .with_additional(["distance"]) \
    .do()

for item in results["data"]["Get"]["Document"]:
    print(f"距离: {item['_additional']['distance']:.4f}, 文本: {item['text']}")

RAG Application Example

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

# Knowledge base documents
knowledge_base = [
    "RouteAPI 是一个统一的 AI API 网关,聚合了 OpenAI、Claude、Gemini 等多家供应商。",
    "RouteAPI 提供统一的认证、计费和监控能力。",
    "RouteAPI 支持流式输出、工具调用和多模态输入。",
    "用户可以通过控制台管理 API Token、查看用量日志和充值余额。"
]

# Generate embeddings for knowledge base
kb_embeddings_response = client.embeddings.create(
    model="text-embedding-3-small",
    input=knowledge_base
)
kb_embeddings = [data.embedding for data in kb_embeddings_response.data]

# User query
user_query = "RouteAPI 有哪些功能?"

# Generate embedding for query
query_response = client.embeddings.create(
    model="text-embedding-3-small",
    input=user_query
)
query_embedding = query_response.data[0].embedding

# Calculate similarity and retrieve most relevant documents
import numpy as np

def cosine_similarity(vec1, vec2):
    return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))

similarities = [cosine_similarity(query_embedding, kb_emb) for kb_emb in kb_embeddings]
top_k = 2
top_indices = np.argsort(similarities)[-top_k:][::-1]

# Build context
context = "\n".join([knowledge_base[i] for i in top_indices])

# Call Chat Completions to generate answer
chat_response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "system", "content": "你是一个 RouteAPI 助手。请根据提供的上下文回答用户问题。"},
        {"role": "user", "content": f"上下文:\n{context}\n\n问题:{user_query}"}
    ]
)

print(chat_response.choices[0].message.content)

Best Practices

1. Choose the Right Embedding Model

Consideration	Recommendation
General scenarios	Use text-embedding-3-small, cost-effective
High precision needs	Use text-embedding-3-large, higher dimensions
Chinese semantics	Consider bge-large-zh and other Chinese-optimized models
Cost priority	Choose lower-dimensional models or use dimensions parameter for reduction

2. Text Preprocessing

def preprocess_text(text):
    """Text preprocessing"""
    # Remove extra whitespace
    text = " ".join(text.split())
    # Limit length (avoid exceeding model limit)
    max_tokens = 8000  # Reserve some space
    if len(text.split()) > max_tokens:
        text = " ".join(text.split()[:max_tokens])
    return text

# Usage
clean_text = preprocess_text(raw_text)
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=clean_text
)

3. Dimension Selection

Some models (such as text-embedding-3-small and text-embedding-3-large) support customizing output dimensions via the dimensions parameter:

# Reduce dimensions to save storage and computation costs
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="RouteAPI 是一个 AI API 网关",
    dimensions=512  # Reduce from default 1536 to 512
)

Dimensionality reduction will slightly reduce precision but can significantly lower storage costs and query latency. It is recommended to test the impact of different dimensions on business metrics during development.

4. Cost Optimization

• Batch processing: Combine multiple texts into one request.
• Cache embeddings: For static documents, generate embeddings once and cache for reuse.
• Choose the right model: Don’t blindly use the largest model, text-embedding-3-small is sufficient for most scenarios.
• Dimensionality reduction: Use the dimensions parameter to reduce vector dimensions.

5. Error Handling

from openai import OpenAI, OpenAIError

client = OpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

def get_embedding_with_retry(text, max_retries=3):
    """Embedding generation with retry"""
    for attempt in range(max_retries):
        try:
            response = client.embeddings.create(
                model="text-embedding-3-small",
                input=text
            )
            return response.data[0].embedding
        except OpenAIError as e:
            if attempt == max_retries - 1:
                raise
            print(f"Request failed, retrying {attempt + 1}/{max_retries}: {e}")
            time.sleep(2 ** attempt)  # Exponential backoff
    return None

6. Performance Optimization

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

async def get_embeddings_batch(texts, batch_size=50):
    """Asynchronously batch get embeddings"""
    results = []
    for i in range(0, len(texts), batch_size):
        batch = texts[i:i + batch_size]
        response = await async_client.embeddings.create(
            model="text-embedding-3-small",
            input=batch
        )
        results.extend([data.embedding for data in response.data])
    return results

# Usage
texts = ["Text 1", "Text 2", ..., "Text 1000"]
embeddings = asyncio.run(get_embeddings_batch(texts))

FAQ

Q: Can embedding vectors be used across models?
No. Different models generate vectors with different dimensions and semantic spaces, you must use the same model to generate both query vectors and document vectors.

Q: How to choose similarity threshold?
Cosine similarity ranges from -1 to 1. Generally:

• 0.8: Highly relevant

• 0.6-0.8: Relevant
• < 0.6: Weakly relevant or irrelevant

Specific thresholds need to be tested and adjusted based on business scenarios.

Q: Common causes of embedding generation failures?

Error	Cause	Solution
invalid_api_key	Invalid token	Check Authorization header
model_not_found	Model ID incorrect or unavailable	Check model ID and account permissions
context_length_exceeded	Input text too long	Shorten text or process in segments
rate_limit_exceeded	Requests too frequent	Reduce concurrency or increase intervals

Q: How to handle multilingual text?
Most embedding models (such as text-embedding-3-small) support multiple languages, but cross-language semantic matching effectiveness depends on model training. For Chinese scenarios, consider bge-large-zh and other Chinese-optimized models first.

Q: How long can embedding vectors be stored?
Embedding vectors are deterministic (same input generates same vector), can be stored and reused long-term, until you switch models or model versions are updated.