Индекс документации

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

Эмбеддинги

MD версия

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

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' }}

  ```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"
  }'
```

</Template>

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

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

<Template data={{ API_KEY_REF, MODEL: 'openai/text-embedding-3-small' }}

  ```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"
    ]
  }'
```

</Template>

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

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

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

<Template data={{ API_KEY_REF, MODEL: 'nvidia/llama-nemotron-embed-vl-1b-v2' }}

  ```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"
  }'
```

</Template>

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

<Template data={{ API_KEY_REF, MODEL: 'nvidia/llama-nemotron-embed-vl-1b-v2' }}

  ```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"
  }'
```

</Template>

Справочник API

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

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

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

https://api.vega.chat/models?fmt=cards&output_modalities=embeddings

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

<Template data={{ API_KEY_REF }}

  ```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"
```

</Template>

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

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

<Template data={{ API_KEY_REF, MODEL: 'openai/text-embedding-3-small' }}

  ```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})")
```

</Template>

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

lines

Search results:
Dogs are loyal companions (similarity: 0.8234)
The cat sat on the mat (similarity: 0.7891)
The weather is sunny today (similarity: 0.3456)
Machine learning models require training data (similarity: 0.2987)
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

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

Для получения дополнительной информации см. Маршрутизация провайдеров.

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

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

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, чтобы автоматически использовать резервные провайдеры.

Ограничения

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

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

Страница моделей — Обзор всех доступных моделей эмбеддингов
Маршрутизация провайдеров — Управление тем, какие провайдеры обслуживают ваши запросы
Аутентификация — Информация об аутентификации с помощью ключа API
Ошибки — Подробные коды ошибок и их обработка