> ## Индекс документации
> Получите полный индекс документации по адресу: https://api.vega.chat/docs/llms.txt
> Используйте этот файл, чтобы узнать о всех доступных страницах перед дальнейшим изучением.

# Эмбеддинги

> Генерировать векторные эмбеддинги из текста и изображений

export const Template = ({children, data}) => {
  const replace = s => s.replace(/\{\{(\w+)\}\}/g, (_, k) => (k in data) ? data[k] : `{{${k}}}`);
  const leafText = node => typeof node === 'string' ? node : node?.$$typeof && typeof node.props?.children === 'string' ? node.props.children : null;
  const collapseTokens = nodes => {
    const out = [];
    let i = 0;
    while (i < nodes.length) {
      const ta = leafText(nodes[i]);
      const tb = leafText(nodes[i + 1]);
      const tc = leafText(nodes[i + 2]);
      if (ta != null && tb != null && tc != null) {
        const m = (ta + tb + tc).match(/^([\s\S]*)\{\{(\w+)\}\}([\s\S]*)$/);
        if (m && (m[2] in data)) {
          out.push(m[1] + data[m[2]] + m[3]);
          i += 3;
          continue;
        }
      }
      out.push(nodes[i]);
      i++;
    }
    return out;
  };
  const process = node => {
    if (typeof node === 'string') return replace(node);
    if (Array.isArray(node)) return collapseTokens(node.map(process));
    if (node && typeof node === 'object') {
      if (node.$$typeof) return {
        ...node,
        props: process(node.props)
      };
      return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, process(v)]));
    }
    return node;
  };
  return <>{process(children)}</>;
};

export const API_KEY_REF = '<OPENROUTER_API_KEY>';

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

## Что такое эмбеддинги?

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

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

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

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

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

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

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

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

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

## Как использовать эмбеддинги

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

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

<Template
  data={{
API_KEY_REF,
MODEL: 'openai/text-embedding-3-small'
}}
>
  <CodeGroup>
    ```typescript title="TypeScript SDK" lines theme={null}
    import { OpenRouter } from '@openrouter/sdk';

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

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

    console.log(response.data[0].embedding);
    ```

    ```python title="Python" lines theme={null}
    import requests

    response = requests.post(
      "https://openrouter.ai/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)" lines theme={null}
    const response = await fetch('https://openrouter.ai/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" lines theme={null}
    curl https://openrouter.ai/api/v1/embeddings \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $OPENROUTER_API_KEY" \
      -d '{
        "model": "{{MODEL}}",
        "input": "The quick brown fox jumps over the lazy dog"
      }'
    ```
  </CodeGroup>
</Template>

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

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

<Template
  data={{
API_KEY_REF,
MODEL: 'openai/text-embedding-3-small'
}}
>
  <CodeGroup>
    ```typescript title="TypeScript SDK" lines theme={null}
    import { OpenRouter } from '@openrouter/sdk';

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

    const response = await openRouter.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'
      ],
    });

    // Process each embedding
    response.data.forEach((item, index) => {
      console.log(`Embedding ${index}: ${item.embedding.length} dimensions`);
    });
    ```

    ```python title="Python" expandable lines theme={null}
    import requests

    response = requests.post(
      "https://openrouter.ai/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)" lines theme={null}
    const response = await fetch('https://openrouter.ai/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" lines theme={null}
    curl https://openrouter.ai/api/v1/embeddings \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $OPENROUTER_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"
        ]
      }'
    ```
  </CodeGroup>
</Template>

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

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

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

<Template
  data={{
API_KEY_REF,
MODEL: 'nvidia/llama-nemotron-embed-vl-1b-v2'
}}
>
  <CodeGroup>
    ```python title="Python" expandable lines theme={null}
    import requests

    response = requests.post(
      "https://openrouter.ai/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)" expandable lines theme={null}
    const response = await fetch('https://openrouter.ai/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" lines theme={null}
    curl https://openrouter.ai/api/v1/embeddings \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $OPENROUTER_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"
      }'
    ```
  </CodeGroup>
</Template>

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

<Template
  data={{
API_KEY_REF,
MODEL: 'nvidia/llama-nemotron-embed-vl-1b-v2'
}}
>
  <CodeGroup>
    ```python title="Python" expandable lines theme={null}
    import requests

    response = requests.post(
      "https://openrouter.ai/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)" expandable lines theme={null}
    const response = await fetch('https://openrouter.ai/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" lines theme={null}
    curl https://openrouter.ai/api/v1/embeddings \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $OPENROUTER_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"
      }'
    ```
  </CodeGroup>
</Template>

## Справочник API

Для подробной информации о параметрах запроса, формате ответа и всех доступных опциях см. [Справочник API эмбеддингов](/docs/api/api-reference/embeddings/submit-an-embedding-request).

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

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

[https://api.vega.chat/models?fmt=cards&output_modalities=embeddings](https://api.vega.chat/models?fmt=cards&output_modalities=embeddings)

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

<Template
  data={{
API_KEY_REF
}}
>
  <CodeGroup>
    ```typescript title="TypeScript SDK" lines theme={null}
    import { OpenRouter } from '@openrouter/sdk';

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

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

    ```python title="Python" lines theme={null}
    import requests

    response = requests.get(
      "https://openrouter.ai/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)" lines theme={null}
    const response = await fetch('https://openrouter.ai/api/v1/embeddings/models', {
      headers: {
        'Authorization': 'Bearer {{API_KEY_REF}}',
      },
    });

    const models = await response.json();
    console.log(models.data);
    ```

    ```shell title="Shell" lines theme={null}
    curl https://openrouter.ai/api/v1/embeddings/models \
      -H "Authorization: Bearer $OPENROUTER_API_KEY"
    ```
  </CodeGroup>
</Template>

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

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

<Template
  data={{
API_KEY_REF,
MODEL: 'openai/text-embedding-3-small'
}}
>
  <CodeGroup>
    ```typescript title="TypeScript SDK" expandable lines theme={null}
    import { OpenRouter } from '@openrouter/sdk';

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

    // Sample documents
    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 to calculate cosine similarity
    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[]) {
      // Generate embeddings for all documents and the query
      const response = await openRouter.embeddings.generate({
        model: '{{MODEL}}',
        input: [query, ...documents],
      });

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

      // Calculate similarity scores
      const results = documents.map((doc, i) => ({
        document: doc,
        similarity: cosineSimilarity(
          queryEmbedding as number[],
          docEmbeddings[i].embedding as number[]
        ),
      }));

      // Sort by similarity (highest first)
      results.sort((a, b) => b.similarity - a.similarity);

      return results;
    }

    // Search for documents related to pets
    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" expandable lines theme={null}
    import requests
    import numpy as np

    OPENROUTER_API_KEY = "{{API_KEY_REF}}"

    # Sample documents
    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):
      """Calculate cosine similarity between two vectors"""
      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):
      """Perform semantic search using embeddings"""
      # Generate embeddings for query and all documents
      response = requests.post(
        "https://openrouter.ai/api/v1/embeddings",
        headers={
          "Authorization": f"Bearer {OPENROUTER_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:]]
      
      # Calculate similarity scores
      results = []
      for i, doc in enumerate(documents):
        similarity = cosine_similarity(query_embedding, doc_embeddings[i])
        results.append({"document": doc, "similarity": similarity})
      
      # Sort by similarity (highest first)
      results.sort(key=lambda x: x["similarity"], reverse=True)
      
      return results

    # Search for documents related to pets
    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})")
    ```
  </CodeGroup>
</Template>

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

```lines theme={null}
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)
```

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

**Choose the right model**: Разные модели эмбеддингов имеют разные сильные стороны. Более мелкие модели (например, qwen/qwen3-embedding-0.6b или openai/text-embedding-3-small) работают быстрее и дешевле, тогда как крупные модели (например, openai/text-embedding-3-large) обеспечивают более высокое качество. Тестируйте несколько моделей, чтобы найти оптимальную для вашего случая.

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

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

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

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

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

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

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

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

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

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

Для получения дополнительной информации см. [Маршрутизация провайдеров](/docs/guides/routing/provider-selection).

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

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

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

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

**402 Payment Required**: Недостаточно кредитов. Добавьте кредиты VEGA в ваш аккаунт VEGA.

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

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

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

## Ограничения

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

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

* [Страница моделей](https://api.vega.chat/models?fmt=cards&output_modalities=embeddings) — Обзор всех доступных моделей эмбеддингов
* [Маршрутизация провайдеров](/docs/guides/routing/provider-selection) — Управление тем, какие провайдеры обслуживают ваши запросы
* [Аутентификация](/docs/api_reference/authentication) — Информация об аутентификации с помощью ключа API
* [Ошибки](/docs/api_reference/errors-and-debugging) — Подробные коды ошибок и их обработка