> Для получения чистого 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

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

## Что такое Embeddings?

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

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

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

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

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

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

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

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

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

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

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

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

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

```typescript title="TypeScript SDK"
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 title="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 title="TypeScript (fetch)"
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 title="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 title="TypeScript SDK"
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 title="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 title="TypeScript (fetch)"
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 title="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 title="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 title="TypeScript (fetch)"
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 title="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 title="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 title="TypeScript (fetch)"
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 title="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](/docs/api-reference/embeddings/create-embeddings).

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

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

[/aimodels?fmt=cards\&output_modalities=embeddings](/aimodels?fmt=cards\&output_modalities=embeddings)

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

```typescript title="TypeScript SDK"
import { OpenRouter } from '@openrouter/sdk';

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

const models = await client.embeddings.listModels();
console.log(models.data);
```

```python title="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 title="TypeScript (fetch)"
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 title="Shell"
curl https://api.vega.chat/api/v1/embeddings/models \
  -H "Authorization: Bearer $VEGA_API_KEY"
```

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

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

```typescript title="TypeScript SDK"
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 title="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](/docs/guides/routing/provider-selection).

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

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

**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](/aimodels?fmt=cards\&output_modalities=embeddings) — просмотр всех доступных моделей эмбеддингов  
* [Provider Routing](/docs/guides/routing/provider-selection) — управление тем, какие провайдеры обслуживают ваши запросы  
* [Authentication](/docs/api/authentication) — аутентификация с помощью API‑ключа  
* [Errors](/docs/api/reference/errors-and-debugging) — подробные коды ошибок и их обработка