Embeddings

Получение векторных представлений текста. Базовый URL: https://api.ru-openrouter.ru/v1/

Embeddings — это числовые представления текста, которые сохраняют семантическое значение. Они преобразуют текст в векторы (массивы чисел), которые можно использовать для различных задач машинного обучения.

Для чего используются Embeddings

• RAG (Retrieval-Augmented Generation): поиск релевантного контекста в базе знаний перед генерацией ответа.
• Семантический поиск: поиск по смыслу, а не по ключевым словам.
• Рекомендательные системы: поиск семантически похожих элементов.
• Кластеризация и классификация: группировка похожих документов.
• Поиск дубликатов: обнаружение повторяющегося контента.

Эндпоинты

POST /v1/embeddings

Генерация векторных представлений текста. Поддерживает OpenAI-совместимые и Яндекс embedding модели.

Параметры запроса

Базовый запрос

curl https://api.ru-openrouter.ru/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": "The quick brown fox jumps over the lazy dog"
  }'

Пример ответа

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0091, ...]
    }
  ],
  "model": "openai/text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8,
    "total_cost": 0.000032,
    "currency": "RUB"
  }
}

Пакетная обработка (batch)

Можно передать массив строк для получения эмбеддингов для нескольких текстов за один запрос:

curl https://api.ru-openrouter.ru/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": [
      "Machine learning is a subset of artificial intelligence",
      "Deep learning uses neural networks with multiple layers",
      "Natural language processing enables computers to understand text"
    ]
  }'

Мультимодальные эмбеддинги (изображения)

Некоторые embedding-модели поддерживают изображения на входе. Для этого используйте формат с content:

curl https://api.ru-openrouter.ru/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -d '{
    "model": "nvidia/llama-nemotron-embed-vl-1b-v2",
    "input": [
      {
        "content": [
          {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
        ]
      }
    ],
    "encoding_format": "float"
  }'

Можно комбинировать текст и изображение:

curl https://api.ru-openrouter.ru/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -d '{
    "model": "nvidia/llama-nemotron-embed-vl-1b-v2",
    "input": [
      {
        "content": [
          {"type": "text", "text": "A scenic boardwalk through a green meadow"},
          {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
        ]
      }
    ],
    "encoding_format": "float"
  }'

Пример на Python

import requests

response = requests.post(
    "https://api.ru-openrouter.ru/v1/embeddings",
    headers={
        "Authorization": "Bearer sk_ваш_api_ключ",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/text-embedding-3-small",
        "input": "The quick brown fox jumps over the lazy dog"
    }
)

data = response.json()
embedding = data["data"][0]["embedding"]
print(f"Embedding dimension: {len(embedding)}")
print(f"Cost: {data['usage']['total_cost']} RUB")

Пример семантического поиска (Python)

import requests
import numpy as np

API_KEY = "sk_ваш_api_ключ"
BASE_URL = "https://api.ru-openrouter.ru/v1"

documents = [
    "The cat sat on the mat",
    "Dogs are loyal companions",
    "Python is a programming language",
    "Machine learning models require training data",
    "The weather is sunny today"
]

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

def semantic_search(query, documents):
    response = requests.post(
        f"{BASE_URL}/embeddings",
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
        json={"model": "openai/text-embedding-3-small", "input": [query] + documents}
    )
    data = response.json()
    query_emb = np.array(data["data"][0]["embedding"])
    doc_embs = [np.array(item["embedding"]) for item in data["data"][1:]]

    results = [
        {"document": doc, "similarity": cosine_similarity(query_emb, doc_embs[i])}
        for i, doc in enumerate(documents)
    ]
    results.sort(key=lambda x: x["similarity"], reverse=True)
    return results

results = semantic_search("pets and animals", documents)
for i, r in enumerate(results):
    print(f"{i+1}. {r['document']} ({r['similarity']:.4f})")

GET /v1/embeddings/models

Список доступных embedding-моделей.

curl https://api.ru-openrouter.ru/v1/embeddings/models \
  -H "Authorization: Bearer sk_ваш_api_ключ"

Пример ответа

{
  "object": "list",
  "data": [
    {
      "id": "openai/text-embedding-3-small",
      "object": "embedding",
      "created": 1709012345,
      "owned_by": "openai"
    }
  ]
}

Дополнительные поля модели

Ограничения

Коды ошибок