Embeddings API — Документация TokSpan

Конечная точка

http
POST https://api.tokspan.com/v1/embeddings

Параметры запроса

Параметр	Тип	Обязательный	Описание
model	string	Да	ID модели эмбеддингов (например, `text-embedding-3-large`, `text-embedding-3-small`, `voyage-3`)
input	string / array	Да	Текст для векторизации. Передайте строку для одного эмбеддинга или массив строк для пакетной обработки (до 2048 элементов на запрос).
dimensions	integer	Нет	Уменьшение размерности вывода для экономии места и ускорения поиска. Поддерживается моделями text-embedding-3. Должно быть ≤ максимальной размерности модели.
encoding_format	string	Нет	`"float"` (по умолчанию) или `"base64"` для компактной передачи.
user	string	Нет	Идентификатор конечного пользователя для мониторинга злоупотреблений.

Одиночный эмбеддинг

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.tokspan.com/v1",
)

response = client.embeddings.create(
    model="text-embedding-3-large",
    input="Your text string for embedding",
    dimensions=1024,  # Optional: reduce dimensions
)

embedding = response.data[0].embedding
print(f"Vector dimension: {len(embedding)}")

Пакетный эмбеддинг

Отправьте до 2048 входных данных в одном запросе для максимальной пропускной способности. Ответ сохраняет порядок входных данных — response.data[0] соответствует input[0].

python
# Batch embedding — process up to 2048 inputs per request
texts = ["First document", "Second document", "Third document"]

response = client.embeddings.create(
    model="text-embedding-3-large",
    input=texts,
    dimensions=1024,
)

for i, data in enumerate(response.data):
    print(f"Text {i}: vector[:5] = {data.embedding[:5]}...")

Уменьшение размерности

Модели, такие как text-embedding-3-large (макс. 3072 измерения) и text-embedding-3-small (макс. 1536), поддерживают уменьшение размерности вывода через параметр dimensions.

Зачем уменьшать размерность?

Меньше места: Вектор с 256 измерениями занимает в 12 раз меньше места, чем 3072 измерения
Быстрее поиск: Меньше измерений = быстрее вычисление косинусного сходства
Достаточное качество: Для большинства задач 256–512 измерений сохраняют ~95%+ семантического качества

Измерений	Хранение (на 1 млн векторов)	Качество	Лучше всего для
256	~1 GB	Хорошее	Масштабный поиск, чувствительные к стоимости приложения
512	~2 GB	Отличное	RAG общего назначения и семантический поиск
1024	~4 GB	Превосходное	Высокоточный поиск, кластеризация
3072	~12 GB	Максимальное	Максимальная точность, небольшие корпуса

Рецепт семантического поиска

python
import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# Embed your document corpus (do this once, store results)
doc_embeddings = client.embeddings.create(model="text-embedding-3-large", input=documents)

# Embed a search query
query_embedding = client.embeddings.create(model="text-embedding-3-large", input="How do I reset my password?")

# Find most similar documents
scores = [cosine_similarity(query_embedding.data[0].embedding, d.embedding) for d in doc_embeddings.data]
top_idx = np.argmax(scores)
print(f"Best match: {documents[top_idx]} (score: {scores[top_idx]:.3f})")

Совет: Для продакшен-RAG сочетайте эмбеддинги с Rerank для двухэтапного пайплайна: грубый поиск с помощью эмбеддингов (быстро + дёшево), затем точное ранжирование по топ-20–50 результатам.

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

Модель	Провайдер	Макс. измерений	Лучше всего для
text-embedding-3-large	OpenAI	3072	Максимальная точность, гибкое уменьшение размерности
text-embedding-3-small	OpenAI	1536	Экономичность, хорошее качество
Cohere Embed v3	Cohere	1024	Мультиязычность, высокая производительность поиска
Voyage AI	Voyage	1024 / 2048	Эмбеддинги для кода и юридических документов
BGE-M3	BAAI	1024	Открытый исходный код, мультиязычность, возможность самостоятельного хостинга

См. страницу Моделей для полного каталога с актуальными ценами за токен.