Embeddings (Intégrations)

Les Embeddings (intégrations) sont une technologie qui convertit le texte en vecteurs de haute dimension, couramment utilisée pour la recherche sémantique, le RAG (génération augmentée par récupération), la classification de texte et le calcul de similarité. RouteAPI fournit une interface Embeddings compatible avec OpenAI standard, prenant en charge plusieurs modèles d’intégration.

Endpoint

POST /v1/embeddings

URL complète:

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

Cas d’utilisation

Scénario	Description
Recherche sémantique	Convertir les documents et requêtes en vecteurs, récupérer le contenu pertinent par similarité
RAG	Récupérer des fragments de documents pertinents comme contexte pour améliorer la qualité de génération du LLM
Classification de texte	Vectoriser le texte pour les tâches de clustering ou de classification
Systèmes de recommandation	Calculer la similarité de texte pour les recommandations de contenu
Détection de doublons	Identifier le contenu dupliqué ou similaire par similarité vectorielle

Exemples de requête

Texte unique

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

Textes en lot

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

Paramètres de requête

Champ	Type	Requis	Description
model	string	Oui	ID du modèle d’intégration
input	string/array	Oui	Chaîne de texte unique ou tableau de textes
encoding_format	string	Non	Format d’encodage vectoriel, float ou base64, par défaut float
dimensions	number	Non	Dimensions du vecteur renvoyé (pris en charge par certains modèles), utilisé pour la réduction de dimensionnalité
user	string	Non	Identifiant utilisateur final, pour le suivi et la surveillance des abus

Exemple de réponse

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

Champs de réponse

Champ	Description
object	Fixé à list
data	Tableau de résultats d’intégration
data[].embedding	Tableau de vecteurs à virgule flottante
data[].index	Position d’index du texte d’entrée
model	ID du modèle réellement utilisé
usage.prompt_tokens	Nombre de tokens consommés par l’entrée
usage.total_tokens	Nombre total de tokens

Modèles d’intégration pris en charge

Modèles OpenAI

ID du modèle	Dimensions par défaut	Performance	Cas d’utilisation
text-embedding-3-small	1536	Rentable	Recherche sémantique générale, RAG
text-embedding-3-large	3072	Haute précision	Tâches sémantiques complexes
text-embedding-ada-002	1536	Classique stable	Rétrocompatibilité

Modèles Google

ID du modèle	Dimensions par défaut	Description
text-embedding-004	768	Dernier modèle d’intégration de Google
gemini-embedding-001	768	Modèle d’intégration de la série Gemini

Autres fournisseurs

ID du modèle	Dimensions par défaut	Fournisseur
text-embedding-v1	1024	Baidu Wenxin
embedding-bert-512-v1	512	Zhipu AI
bge-large-zh	1024	BAAI BGE (chinois)
bge-large-en	1024	BAAI BGE (anglais)

La disponibilité des modèles est soumise à la liste des modèles de la console, différents comptes peuvent avoir différents modèles disponibles.

Traitement par lots

Limites de taille de lot

• Le nombre maximum de textes traités dans une seule requête dépend du modèle spécifique et de la configuration du service.
• Il est recommandé de ne pas dépasser 100 textes par requête.
• Le nombre de tokens d’un seul texte ne doit généralement pas dépasser la limite d’entrée maximale du modèle (généralement 8192 tokens).

Conseils d’optimisation par lots

1. Fusionner les requêtes: Combiner plusieurs textes courts en une seule requête pour réduire les allers-retours réseau.
2. Contrôle de la concurrence: Les tâches de lots importants peuvent être divisées et traitées simultanément, la concurrence recommandée ne doit pas dépasser 5.
3. Gestion des erreurs: Lorsqu’un texte d’un lot échoue, la requête entière peut échouer, une nouvelle tentative et une gestion des erreurs appropriées sont nécessaires.

Exemples de code

Python (SDK OpenAI)

from openai import OpenAI

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

# Texte unique
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]}")

# Textes en lot
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 (SDK OpenAI)

import OpenAI from 'openai';

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

async function getEmbedding() {
  // Texte unique
  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)}`);

  // Textes en lot
  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"]
  }'

Calcul de similarité sémantique

Python (Utilisation de 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):
    """Calculer la similarité cosinus"""
    return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))

# Obtenir les vecteurs d'intégration de deux textes
texts = [
    "RouteAPI 是一个 AI API 网关",
    "RouteAPI 提供统一的模型接入服务",
    "今天天气很好"
]

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

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

# Calculer la similarité
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}")  # Haute similarité
print(f"文本0 和 文本2 的相似度: {sim_0_2:.4f}")  # Faible similarité

Node.js (Utilisation de bibliothèque mathématique)

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

Intégration de base de données vectorielle

Exemple Pinecone

from openai import OpenAI
import pinecone

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

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

# Générer des intégrations et stocker
documents = [
    {"id": "doc1", "text": "RouteAPI 是一个 AI API 网关"},
    {"id": "doc2", "text": "支持多家 AI 模型供应商"},
    {"id": "doc3", "text": "提供统一的接口和计费"}
]

for doc in documents:
    # Générer l'intégration
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=doc["text"]
    )
    embedding = response.data[0].embedding

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

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

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

Exemple Weaviate

import weaviate
from openai import OpenAI

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

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

# Créer un schéma (s'il n'existe pas)
schema = {
    "class": "Document",
    "vectorizer": "none",  # Nous fournissons nous-mêmes les vecteurs
    "properties": [
        {"name": "text", "dataType": ["text"]}
    ]
}

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

for doc_text in documents:
    # Générer l'intégration
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=doc_text
    )
    embedding = response.data[0].embedding

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

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

# Recherche vectorielle
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']}")

Exemple d’application RAG

from openai import OpenAI

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

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

# Générer des intégrations pour la base de connaissances
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]

# Requête utilisateur
user_query = "RouteAPI 有哪些功能?"

# Générer l'intégration pour la requête
query_response = client.embeddings.create(
    model="text-embedding-3-small",
    input=user_query
)
query_embedding = query_response.data[0].embedding

# Calculer la similarité et récupérer les documents les plus pertinents
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]

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

# Appeler Chat Completions pour générer la réponse
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)

Meilleures pratiques

1. Choisir le bon modèle d’intégration

Considération	Recommandation
Scénarios généraux	Utiliser text-embedding-3-small, rentable
Besoins haute précision	Utiliser text-embedding-3-large, dimensions plus élevées
Sémantique chinoise	Considérer bge-large-zh et autres modèles optimisés pour le chinois
Priorité coût	Choisir des modèles de dimension inférieure ou utiliser le paramètre dimensions pour la réduction

2. Prétraitement du texte

def preprocess_text(text):
    """Prétraitement du texte"""
    # Supprimer les espaces supplémentaires
    text = " ".join(text.split())
    # Limiter la longueur (éviter de dépasser la limite du modèle)
    max_tokens = 8000  # Réserver un peu d'espace
    if len(text.split()) > max_tokens:
        text = " ".join(text.split()[:max_tokens])
    return text

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

3. Sélection de dimension

Certains modèles (tels que text-embedding-3-small et text-embedding-3-large) prennent en charge la personnalisation des dimensions de sortie via le paramètre dimensions.

# Réduire les dimensions pour économiser les coûts de stockage et de calcul
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="RouteAPI 是一个 AI API 网关",
    dimensions=512  # Réduire de 1536 par défaut à 512
)

La réduction de dimensionnalité réduira légèrement la précision mais peut considérablement réduire les coûts de stockage et la latence des requêtes. Il est recommandé de tester l’impact de différentes dimensions sur les métriques métier pendant le développement.

4. Optimisation des coûts

• Traitement par lots: Combiner plusieurs textes en une seule requête.
• Mise en cache des intégrations: Pour les documents statiques, générer les intégrations une fois et les mettre en cache pour réutilisation.
• Choisir le bon modèle: Ne pas utiliser aveuglément le plus grand modèle, text-embedding-3-small suffit pour la plupart des scénarios.
• Réduction de dimensionnalité: Utiliser le paramètre dimensions pour réduire les dimensions vectorielles.

5. Gestion des erreurs

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):
    """Génération d'intégration avec nouvelle tentative"""
    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"Échec de la requête, nouvelle tentative {attempt + 1}/{max_retries}: {e}")
            time.sleep(2 ** attempt)  # Backoff exponentiel
    return None

6. Optimisation des performances

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):
    """Obtenir des intégrations par lots de manière asynchrone"""
    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

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

FAQ

Q: Les vecteurs d’intégration peuvent-ils être utilisés entre les modèles?
Non. Différents modèles génèrent des vecteurs avec des dimensions et des espaces sémantiques différents, vous devez utiliser le même modèle pour générer à la fois les vecteurs de requête et les vecteurs de documents.

Q: Comment choisir le seuil de similarité?
La similarité cosinus varie de -1 à 1. Généralement:

• 0.8: Très pertinent

• 0.6-0.8: Pertinent
• < 0.6: Faiblement pertinent ou non pertinent

Les seuils spécifiques doivent être testés et ajustés en fonction des scénarios métier.

Q: Causes courantes d’échec de génération d’intégration?

Erreur	Cause	Solution
invalid_api_key	Token invalide	Vérifier l’en-tête Authorization
model_not_found	ID de modèle incorrect ou indisponible	Vérifier l’ID du modèle et les autorisations du compte
context_length_exceeded	Texte d’entrée trop long	Raccourcir le texte ou traiter par segments
rate_limit_exceeded	Requêtes trop fréquentes	Réduire la concurrence ou augmenter les intervalles

Q: Comment gérer le texte multilingue?
La plupart des modèles d’intégration (tels que text-embedding-3-small) prennent en charge plusieurs langues, mais l’efficacité de la correspondance sémantique inter-langues dépend de l’entraînement du modèle. Pour les scénarios chinois, considérez d’abord bge-large-zh et autres modèles optimisés pour le chinois.

Q: Combien de temps les vecteurs d’intégration peuvent-ils être stockés?
Les vecteurs d’intégration sont déterministes (la même entrée génère le même vecteur), peuvent être stockés et réutilisés à long terme, jusqu’à ce que vous changiez de modèle ou que les versions du modèle soient mises à jour.