Embeddings — векторизация текста

Преобразуйте текст в числовые векторы для семантического поиска, кластеризации, рекомендаций и RAG. Эндпоинт полностью совместим с OpenAI Embeddings — те же поля и формат ответа.

Модели и цены

Цены итоговые — именно столько списывается с баланса. Полный список и тарифы — в разделе Модели и цены. Для большинства задач начните с text-embedding-3-small и переходите на -large при высоких требованиях к точности.

Размерность вектора (параметр dimensions)

Модели text-embedding-3-small (до 1536) и text-embedding-3-large (до 3072) позволяют усечь вектор параметром dimensions. Меньшая размерность экономит память и ускоряет поиск в векторной БД при небольшой потере точности. В MegaAPI Chat нужное значение выбирается в поле «Размерность вектора» (появляется только для моделей -3-*); для остальных моделей параметр не применяется и сервер вернёт понятную ошибку до списания.

{
    "model": "text-embedding-3-large",
    "input": "Искусственный интеллект меняет мир",
    "dimensions": 1024
}

Запрос

POST https://megaapi.ru/v1/embeddings
Authorization: Bearer sk-...
Content-Type: application/json

{
    "model": "text-embedding-3-small",
    "input": "Искусственный интеллект меняет мир"
}

Батч (несколько текстов за раз)

Отправляйте до 2048 строк одним запросом — это снижает сетевые издержки:

{
    "model": "text-embedding-3-small",
    "input": ["первый текст", "второй текст", "третий текст"]
}

Ответ

{
    "object": "list",
    "data": [{ "object": "embedding", "index": 0,
              "embedding": [-0.0069, 0.0240, -0.0140, ...] }],
    "model": "text-embedding-3-small",
    "usage": { "prompt_tokens": 5, "total_tokens": 5 }
}

Пример: семантический поиск

Векторизуйте запрос и документы, ранжируйте по косинусной близости:

import numpy as np
from openai import OpenAI

client = OpenAI(api_key="sk-...", base_url="https://megaapi.ru/v1")

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

documents = [
    "Python — высокоуровневый язык программирования",
    "Машинное обучение требует много данных",
    "Глубокое обучение — важная ветвь ИИ",
]
query = "искусственный интеллект и обучение"

resp = client.embeddings.create(model="text-embedding-3-small", input=[query] + documents)
vecs = [d.embedding for d in resp.data]
scores = [cosine(vecs[0], v) for v in vecs[1:]]

for doc, s in sorted(zip(documents, scores), key=lambda x: -x[1]):
    print(f"{s:.4f}  {doc}")

Сценарии применения

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

Лучшие практики

• Чанкинг. Длинные документы режьте на куски (~500 токенов) с небольшим перекрытием.
• Кэширование. Храните векторы повторяющихся текстов, чтобы не пересчитывать.
• Косинусная близость. Для сравнения векторов используйте cosine similarity.
• Хранилище. Для продакшена подключайте векторную БД (Pinecone, Milvus, Weaviate, pgvector).

Переранжирование: /v1/rerank

Векторный поиск отвечает на вопрос «о чём этот текст», но не на вопрос «отвечает ли он на мой запрос». Из-за этого в топ выдачи попадают документы той же темы, которые пользователю не нужны. Переранжирование ставится вторым шагом после векторного поиска: модель получает запрос и каждого кандидата вместе и выдаёт оценку релевантности.

curl https://megaapi.ru/v1/rerank \
  -H "Authorization: Bearer $MEGAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "как настроить повторные попытки при 429",
    "documents": [
      "Коды 4xx означают ошибку на стороне клиента.",
      "При 429 используйте экспоненциальную задержку между повторами.",
      "Плановые работы в дата-центре 29 апреля."
    ],
    "top_n": 2
  }'

В ответе документы отсортированы по убыванию релевантности:

{
  "results": [
    { "index": 1, "relevance_score": 0.97, "document": { "text": "При 429 используйте…" } },
    { "index": 0, "relevance_score": 0.42, "document": { "text": "Коды 4xx означают…" } }
  ],
  "usage": { "prompt_tokens": 70, "total_tokens": 91 }
}

Важные лимиты

Открыть в MegaAPI Chat → Полный справочник API Все модели