Эмбеддинги

POST https://api.aitunnel.ru/v1/embeddings — OpenAI-совместимый эндпоинт. Стриминга нет: ответ приходит целиком.

Зачем

• RAG — найти куски базы знаний, которые стоит подставить в контекст модели. Пайплайн целиком — руководство по RAG. После поиска часто идёт ранжирование.
• Семантический поиск — искать по смыслу, а не по точным словам
• Рекомендации — близкие товары, статьи, ролики
• Кластеризация и классификация — похожие документы в одну группу
• Дубликаты — пересказ того же текста тоже ловится
• Аномалии — векторы далеко от типичных

Запрос

Нужны model и input — строка или массив строк.

curl https://api.aitunnel.ru/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "Искусственный интеллект изменяет мир технологий"
  }'

Несколько текстов — один запрос, дешевле и быстрее, чем по одному:

curl https://api.aitunnel.ru/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -d '{
    "model": "text-embedding-3-small",
    "input": [
      "Машинное обучение — раздел искусственного интеллекта",
      "Глубокое обучение использует многослойные нейросети",
      "NLP позволяет компьютерам понимать текст"
    ]
  }'

Ответ

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023064255, -0.009327292]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12,
    "cost_rub": 0.01,
    "balance": 950.5
  }
}

В usage — токены, cost_rub и balance после списания. Списывается фактический объём входа, не максимум модели.

Картинки

У части моделей во входе есть image — смотрите modalities.input в каталоге. Тогда input — массив объектов с content: text и image_url. URL или data:…;base64. Это вектор для поиска, не описание картинки. Описание, OCR и генерация — картинки.

Пример на voyage-multimodal-3.5 (текст + картинка в одном векторе):

curl https://api.aitunnel.ru/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -d '{
    "model": "voyage-multimodal-3.5",
    "input": [
      {
        "content": [
          {"type": "text", "text": "Деревянный настил через зелёный луг"},
          {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/640px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"}}
        ]
      }
    ]
  }'

Какие модели

Актуальный список — группа embeddings в каталоге и в публичном API без ключа:

curl https://api.aitunnel.ru/public/aitunnel/models/embeddings

Имена для поля model: text-embedding-3-small, voyage-4, qwen3-embedding-8b, gigachat-embeddings-2 и другие. Слаг provider/model уходит в OpenRouter.

Семантический поиск

import numpy as np

docs = [
    "Python — язык программирования",
    "Москва — столица России",
    "Нейросети обучаются на данных",
]

doc_res = client.embeddings.create(model="text-embedding-3-small", input=docs)
query_res = client.embeddings.create(
    model="text-embedding-3-small",
    input="Какой язык используется для ИИ?",
)
query = query_res.data[0].embedding

def cosine(a, b):
    a, b = np.array(a), np.array(b)
    return float(a @ b / (np.linalg.norm(a) * np.linalg.norm(b)))

for doc, item in zip(docs, doc_res.data):
    print(f"{cosine(query, item.embedding):.4f}  {doc}")

Сравнивайте косинусом, не евклидовым расстоянием: для длинных векторов так устойчивее.

Практика

• Маленькая модель быстрее и дешевле; большая — точнее. Для старта хватает text-embedding-3-small.
• Пакуйте тексты в один input, не долбите API по одному.
• Много однотипных запросов — Batch запросы, если у модели в каталоге есть batch.
• Один и тот же текст даёт один и тот же вектор. Сохраняйте результат, не считайте повторно.
• Не превышайте контекст модели. Длинный документ режьте по абзацам и заголовкам, не по произвольным N символам.

Ограничения

• Стрима нет.
• Текст длиннее окна модели обрежут или отклонят — зависит от провайдера.
• Температуры нет: повтор того же input даёт тот же вектор.
• Не все модели понимают все языки и картинки — смотрите карточку в каталоге.

Ошибки — те же коды, что у остального API: ошибки и отладка.