Для получения чистого Markdown любой страницы добавьте .md к URL‑адресу страницы.
Для полного индекса документации см. https://api.vega.chat/docs/llms.txt.
Для полного содержимого документации см. https://api.vega.chat/docs/llms-full.txt.
Для интеграции AI‑клиентов (Claude Code, Cursor и др.) подключитесь к серверу MCP по адресу https://api.vega.chat/docs/_mcp/server.

Embeddings

MD версия

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

Что такое Embeddings?

Эмбеддинги преобразуют текст в векторы высокой размерности, где семантически похожие тексты находятся ближе друг к другу в векторном пространстве. Например, «cat» и «kitten» будут иметь схожие эмбеддинги, тогда как «cat» и «airplane» будут расположены далеко друг от друга.

Эти векторные представления позволяют машинам понимать взаимосвязи между фрагментами текста, что делает их незаменимыми для множества AI‑приложений.

Распространённые сценарии использования

Эмбеддинги применяются в самых разных областях:

RAG (Retrieval‑Augmented Generation): создавайте RAG‑системы, которые извлекают релевантный контекст из базы знаний перед генерацией ответов. Эмбеддинги помогают находить наиболее подходящие документы для включения в контекст LLM.

Семантический поиск: преобразуйте документы и запросы в эмбеддинги, а затем находите наиболее релевантные документы, сравнивая векторное сходство. Это даёт более точные результаты, чем традиционный поиск по ключевым словам, потому что учитывается смысл, а не только совпадения слов.

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

Кластеризация и классификация: группируйте похожие документы вместе или классифицируйте текст по категориям, анализируя паттерны эмбеддингов. Документы с похожими эмбеддингами, как правило, относятся к одной теме или категории.

Обнаружение дубликатов: определяйте дублирующий или почти дублирующий контент, сравнивая сходство эмбеддингов. Это работает даже при перефразировании или изменении формулировок.

Обнаружение аномалий: выявляйте необычный или выбивающийся контент, находя эмбеддинги, которые сильно отклоняются от типичных паттернов в вашем наборе данных.

Как использовать Embeddings

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

Чтобы сгенерировать эмбеддинги, отправьте POST‑запрос на /embeddings с вашим текстовым вводом и выбранной моделью:

typescript
import { OpenRouter } from '@openrouter/sdk';

const client = new OpenRouter({
  apiKey: '{{API_KEY_REF}}',
});

const response = await client.embeddings.generate({
  model: '{{MODEL}}',
  input: 'The quick brown fox jumps over the lazy dog',
});

console.log(response.data[0].embedding);
python
import requests

response = requests.post(
  "https://api.vega.chat/api/v1/embeddings",
  headers={
    "Authorization": f"Bearer {{API_KEY_REF}}",
    "Content-Type": "application/json",
  },
  json={
    "model": "{{MODEL}}",
    "input": "The quick brown fox jumps over the lazy dog"
  }
)

data = response.json()
embedding = data["data"][0]["embedding"]
print(f"Embedding dimension: {len(embedding)}")
typescript
const response = await fetch('https://api.vega.chat/api/v1/embeddings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{API_KEY_REF}}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '{{MODEL}}',
    input: 'The quick brown fox jumps over the lazy dog',
  }),
});

const data = await response.json();
const embedding = data.data[0].embedding;
console.log(`Embedding dimension: ${embedding.length}`);
shell
curl https://api.vega.chat/api/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VEGA_API_KEY" \
  -d '{
    "model": "{{MODEL}}",
    "input": "The quick brown fox jumps over the lazy dog"
  }'

Пакетная обработка

Вы можете генерировать эмбеддинги для нескольких текстов в одном запросе, передав массив строк:

typescript
import { OpenRouter } from '@openrouter/sdk';

const client = new OpenRouter({
  apiKey: '{{API_KEY_REF}}',
});

const response = await client.embeddings.generate({
  model: '{{MODEL}}',
  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'
  ],
});

// Обрабатываем каждый эмбеддинг
response.data.forEach((item, index) => {
  console.log(`Embedding ${index}: ${item.embedding.length} dimensions`);
});
python
import requests

response = requests.post(
  "https://api.vega.chat/api/v1/embeddings",
  headers={
    "Authorization": f"Bearer {{API_KEY_REF}}",
    "Content-Type": "application/json",
  },
  json={
    "model": "{{MODEL}}",
    "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"
    ]
  }
)

data = response.json()
for i, item in enumerate(data["data"]):
  print(f"Embedding {i}: {len(item['embedding'])} dimensions")
typescript
const response = await fetch('https://api.vega.chat/api/v1/embeddings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{API_KEY_REF}}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '{{MODEL}}',
    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'
    ],
  }),
});

const data = await response.json();
data.data.forEach((item, index) => {
  console.log(`Embedding ${index}: ${item.embedding.length} dimensions`);
});
shell
curl https://api.vega.chat/api/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VEGA_API_KEY" \
  -d '{
    "model": "{{MODEL}}",
    "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"
    ]
  }'

Ввод изображений

Некоторые модели эмбеддингов поддерживают ввод изображений, позволяя создавать мультимодальные эмбеддинги, фиксирующие визуальное содержание вместе с текстом. Это полезно для поиска по изображениям, визуального сходства и кросс‑модальных задач извлечения.

Чтобы отправить изображение, оберните ввод в мультимодальный формат с массивом content, содержащим объекты image_url. Вы также можете комбинировать текст и изображения в одном блоке ввода.

python
import requests

response = requests.post(
  "https://api.vega.chat/api/v1/embeddings",
  headers={
    "Authorization": f"Bearer {{API_KEY_REF}}",
    "Content-Type": "application/json",
  },
  json={
    "model": "{{MODEL}}",
    "input": [
      {
        "content": [
          {"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"}}
        ]
      }
    ],
    "encoding_format": "float",
  }
)

data = response.json()
embedding = data["data"][0]["embedding"]
print(f"Embedding dimension: {len(embedding)}")
typescript
const response = await fetch('https://api.vega.chat/api/v1/embeddings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{API_KEY_REF}}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '{{MODEL}}',
    input: [
      {
        content: [
          { 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' } }
        ]
      }
    ],
    encoding_format: 'float',
  }),
});

const data = await response.json();
const embedding = data.data[0].embedding;
console.log(`Embedding dimension: ${embedding.length}`);
shell
curl https://api.vega.chat/api/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VEGA_API_KEY" \
  -d '{
    "model": "{{MODEL}}",
    "input": [
      {
        "content": [
          {"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"}}
        ]
      }
    ],
    "encoding_format": "float"
  }'

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

python
import requests

response = requests.post(
  "https://api.vega.chat/api/v1/embeddings",
  headers={
    "Authorization": f"Bearer {{API_KEY_REF}}",
    "Content-Type": "application/json",
  },
  json={
    "model": "{{MODEL}}",
    "input": [
      {
        "content": [
          {"type": "text", "text": "A scenic boardwalk through a green meadow"},
          {"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"}}
        ]
      }
    ],
    "encoding_format": "float",
  }
)

data = response.json()
embedding = data["data"][0]["embedding"]
print(f"Embedding dimension: {len(embedding)}")
typescript
const response = await fetch('https://api.vega.chat/api/v1/embeddings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{API_KEY_REF}}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '{{MODEL}}',
    input: [
      {
        content: [
          { type: 'text', text: 'A scenic boardwalk through a green meadow' },
          { 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' } }
        ]
      }
    ],
    encoding_format: 'float',
  }),
});

const data = await response.json();
const embedding = data.data[0].embedding;
console.log(`Embedding dimension: ${embedding.length}`);
shell
curl https://api.vega.chat/api/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VEGA_API_KEY" \
  -d '{
    "model": "{{MODEL}}",
    "input": [
      {
        "content": [
          {"type": "text", "text": "A scenic boardwalk through a green meadow"},
          {"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"}}
        ]
      }
    ],
    "encoding_format": "float"
  }'

Справочник API

Подробную информацию о параметрах запросов, формате ответов и всех доступных опциях см. в Embeddings API Reference.

Доступные модели

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

/aimodels?fmt=cards&output_modalities=embeddings

Чтобы программно получить список всех доступных моделей эмбеддингов:

typescript
import { OpenRouter } from '@openrouter/sdk';

const client = new OpenRouter({
  apiKey: '{{API_KEY_REF}}',
});

const models = await client.embeddings.listModels();
console.log(models.data);
python
import requests

response = requests.get(
  "https://api.vega.chat/api/v1/embeddings/models",
  headers={
    "Authorization": f"Bearer {{API_KEY_REF}}",
  }
)

models = response.json()
for model in models["data"]:
  print(f"{model['id']}: {model.get('context_length', 'N/A')} tokens")
typescript
const response = await fetch('https://api.vega.chat/api/v1/embeddings/models', {
  headers: {
    'Authorization': 'Bearer {{API_KEY_REF}}',
  },
});

const models = await response.json();
console.log(models.data);
shell
curl https://api.vega.chat/api/v1/embeddings/models \
  -H "Authorization: Bearer $VEGA_API_KEY"

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

Ниже приведён полный пример построения системы семантического поиска с использованием эмбеддингов:

typescript
import { OpenRouter } from '@openrouter/sdk';

const client = new OpenRouter({
  apiKey: '{{API_KEY_REF}}',
});

// Пример документов
const 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"
];

// Функция для вычисления косинусного сходства
function cosineSimilarity(a: number[], b: number[]): number {
  const dotProduct = a.reduce((sum, val, i) => sum + val * b[i], 0);
  const magnitudeA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));
  const magnitudeB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));
  return dotProduct / (magnitudeA * magnitudeB);
}

async function semanticSearch(query: string, documents: string[]) {
  // Генерируем эмбеддинги для всех документов и запроса
  const response = await client.embeddings.generate({
    model: '{{MODEL}}',
    input: [query, ...documents],
  });

  const queryEmbedding = response.data[0].embedding;
  const docEmbeddings = response.data.slice(1);

  // Вычисляем оценки сходства
  const results = documents.map((doc, i) => ({
    document: doc,
    similarity: cosineSimilarity(
      queryEmbedding as number[],
      docEmbeddings[i].embedding as number[]
    ),
  }));

  // Сортируем по убыванию сходства
  results.sort((a, b) => b.similarity - a.similarity);

  return results;
}

// Поиск документов, связанных с животными
const results = await semanticSearch("pets and animals", documents);
console.log("Search results:");
results.forEach((result, i) => {
  console.log(`${i + 1}. ${result.document} (similarity: ${result.similarity.toFixed(4)})`);
});
python
import requests
import numpy as np

VEGA_API_KEY = "{{API_KEY_REF}}"

# Пример документов
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):
  """Вычисляет косинусное сходство между двумя векторами"""
  dot_product = np.dot(a, b)
  magnitude_a = np.linalg.norm(a)
  magnitude_b = np.linalg.norm(b)
  return dot_product / (magnitude_a * magnitude_b)

def semantic_search(query, documents):
  """Выполняет семантический поиск с помощью эмбеддингов"""
  # Генерируем эмбеддинги для запроса и всех документов
  response = requests.post(
    "https://api.vega.chat/api/v1/embeddings",
    headers={
      "Authorization": f"Bearer {VEGA_API_KEY}",
      "Content-Type": "application/json",
    },
    json={
      "model": "{{MODEL}}",
      "input": [query] + documents
    }
  )
  
  data = response.json()
  query_embedding = np.array(data["data"][0]["embedding"])
  doc_embeddings = [np.array(item["embedding"]) for item in data["data"][1:]]
  
  # Вычисляем оценки сходства
  results = []
  for i, doc in enumerate(documents):
    similarity = cosine_similarity(query_embedding, doc_embeddings[i])
    results.append({"document": doc, "similarity": similarity})
  
  # Сортируем по убыванию сходства
  results.sort(key=lambda x: x["similarity"], reverse=True)
  
  return results

# Поиск документов, связанных с животными
results = semantic_search("pets and animals", documents)
print("Search results:")
for i, result in enumerate(results):
  print(f"{i + 1}. {result['document']} (similarity: {result['similarity']:.4f})")

Ожидаемый вывод:

Search results: 1. Dogs are loyal companions (similarity: 0.8234) 2. The cat sat on the mat (similarity: 0.7891) 3. The weather is sunny today (similarity: 0.3456) 4. Machine learning models require training data (similarity: 0.2987) 5. Python is a programming language (similarity: 0.2654)

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

Выбор правильной модели: разные модели эмбеддингов имеют разные сильные стороны. Маленькие модели (например, qwen/qwen3-embedding-0.6b или openai/text-embedding-3-small) работают быстрее и дешевле, тогда как крупные модели (например, openai/text-embedding-3-large) обеспечивают более высокое качество. Протестируйте несколько моделей, чтобы найти оптимальную для вашего случая.

Пакетировать запросы: при обработке множества текстов отправляйте их в одном запросе, а не делайте отдельные вызовы API. Это снижает задержку и стоимость.

Кешировать эмбеддинги: эмбеддинги для одного и того же текста детерминированы (не меняются). Сохраняйте их в базе данных или векторном хранилище, чтобы не генерировать их повторно.

Нормализовать для сравнения: при сравнении эмбеддингов используйте косинусное сходство, а не евклидову дистанцию. Косинусное сходство инвариантно к масштабу и лучше работает с векторами высокой размерности.

Учитывать длину контекста: у каждой модели есть максимальная длина входа (окно контекста). Длинные тексты могут потребовать разбиения или усечения. Проверьте спецификации модели перед обработкой больших документов.

Использовать разумное разбиение: для длинных документов разбивайте их на смысловые куски (параграфы, секции), а не на произвольные ограничения по количеству символов. Это сохраняет семантическую согласованность.

Маршрутизация провайдеров

Вы можете управлять тем, какие провайдеры обслуживают ваши запросы к эмбеддингам, используя параметр provider. Это полезно для:

  • Обеспечения конфиденциальности данных с конкретными провайдерами
  • Оптимизации стоимости или задержки
  • Использования специфических функций провайдера

Пример с предпочтениями провайдеров:

typescript
{
  "model": "openai/text-embedding-3-small",
  "input": "Your text here",
  "provider": {
    "order": ["openai", "azure"],
    "allow_fallbacks": true,
    "data_collection": "deny"
  }
}

Подробнее см. Provider Routing.

Обработка ошибок

Распространённые ошибки, с которыми вы можете столкнуться:

400 Bad Request: неверный формат ввода или отсутствие обязательных параметров. Проверьте, что параметры input и model правильно сформированы.

401 Unauthorized: неверный или отсутствующий API‑ключ. Убедитесь, что ваш ключ корректен и включён в заголовок Authorization.

402 Payment Required: недостаточно средств. Пополните баланс вашего аккаунта VEGA.

404 Not Found: указанная модель не существует или недоступна для эмбеддингов. Проверьте название модели и убедитесь, что это модель эмбеддингов.

429 Too Many Requests: превышен лимит запросов. Реализуйте экспоненциальную задержку и повторные попытки.

529 Provider Overloaded: провайдер временно перегружен. Включите allow_fallbacks: true, чтобы автоматически использовать резервные провайдеры.

Ограничения

  • Отсутствие стриминга: в отличие от чат‑завершений, эмбеддинги возвращаются полностью. Потоковая передача не поддерживается.
  • Лимиты токенов: у каждой модели есть максимальная длина входа. Тексты, превышающие этот лимит, будут усечены или отклонены.
  • Детерминированный вывод: эмбеддинги для одинакового входного текста всегда одинаковы (нет температуры или случайности).
  • Поддержка языков: некоторые модели оптимизированы под определённые языки. Ознакомьтесь с документацией модели, чтобы узнать её языковые возможности.

Связанные ресурсы

  • Models Page — просмотр всех доступных моделей эмбеддингов
  • Provider Routing — управление тем, какие провайдеры обслуживают ваши запросы
  • Authentication — аутентификация с помощью API‑ключа
  • Errors — подробные коды ошибок и их обработка