Перейти к основному содержанию
Chroma — векторная база на Python: коллекции, в которые кладутся тексты, векторы и метаданные, и метод query для поиска похожих фрагментов. Chroma ничего не генерирует — она отвечает только за retrieval, а ответ пишет языковая модель. Поэтому Chroma используют вместе с отдельным провайдером генерации, и в этом руководстве им будет SpeShu.AI: один OpenAI-совместимый base_url, один ключ, доступ к каталогу моделей.
От SpeShu.AI Chroma получает ровно две вещи: базовый адрес base_url = "https://speshu.ai/api/v1" и API-ключ. Никакой другой настройки не требуется — ни моделей в белом списке, ни плагинов, ни параметров провайдера. Клиенты с поддержкой OpenAI-совместимых адресов (openai, langchain_openai.ChatOpenAI, llama_index) подключаются одним аргументом.
Эндпоинта эмбеддингов у SpeShu.AI нет: POST /api/v1/embeddings не существует, и запрос к нему вернёт 404. Chroma хранит векторы, но не вычисляет их — поэтому шаг эмбеддинга в пайплайне придётся закрыть отдельно. Два честных варианта:(а) Рекомендуемый. Считайте векторы через отдельный провайдер эмбеддингов, а генерацию оставьте на SpeShu.AI. В коде ниже это два независимых конфига: EMBEDDING_* — чужой провайдер, SPESHU_* — SpeShu.AI. Так смена провайдера эмбеддингов не затрагивает генерацию, и наоборот.(б) Без эмбеддингов вовсе. Используйте Chroma только как хранилище документов с метаданными и фильтром по where, а контекст собирайте вручную. Схема RAG без векторного поиска — это обычный чат с документами, и он уже умеет работать на одном ключе.

Установка

1

Установите пакеты

Для варианта с LangChain поверх того же адреса:
2

Задайте ключ и идентификатор модели

Идентификатор текстовой модели не зашивайте в код: состав каталога меняется, и зашитый в код идентификатор падает с 404 model_not_found. Возьмите его из каталога:
cURL
В коде ниже это переменная окружения SPESHU_MODEL. Формат ответа — в разделе Каталог моделей.
3

Задайте отдельный провайдер эмбеддингов

Нужен только для варианта (а) — если векторы вы считаете не в SpeShu.AI.

Конфигурация

Chroma не обращается к LLM: у неё нет параметров base_url или api_key. Клиент генерации — отдельный объект, и именно он подключается к SpeShu.AI:
Python
chromadb.PersistentClient(path=...) переживает перезапуск процесса — это вариант для ноутбука и пет-проекта. Внутрипроцессный chromadb.EphemeralClient() стирает коллекцию при выходе, а chromadb.HttpClient(host=..., port=...) говорит с развёрнутым сервером Chroma. Все три конструктора стабильны, начиная с chromadb 0.4.16.
Векторы вы считаете сами и передаёте в Chroma явно — параметрами embeddings у add и query_embeddings у query. Это самая устойчивая точка API Chroma: встроенная функция эмбеддинга (OpenAIEmbeddingFunction из chromadb.utils.embedding_functions) меняет сигнатуру между версиями, а явные векторы работают одинаково везде.

Первый рабочий пример

Полный проход: разбить документы на чанки, положить их в коллекцию, найти релевантные и получить ответ от модели SpeShu.AI.
Python
collection.add на существующей коллекции с теми же ids обновит записи, а не продублирует их — перезапуск скрипта безопасен. Список идентификаторов всегда должен совпадать по длине с documents и embeddings, иначе Chroma отклонит запрос.

Вариант без эмбеддингов

Если векторный поиск не нужен, коллекция остаётся хранилищем текста, а отбор фрагментов делает сама Chroma по метаданным:
Python
Здесь векторы не нужны — get возвращает документы напрямую. Дальше контекст уходит в speshu.chat.completions.create тем же кодом, что и выше.

Продвинутые сценарии

Потоковый ответ

speshu.chat.completions.create(..., stream=True) отдаёт SSE, Chroma на это не влияет: контекст собирается синхронно, генерация — по частям. Разбор кадров, маркер [DONE] и кадр со списанием — в разделе Потоковая передача.

Вызов функций

Если вы собираете RAG через LangChain, чат-модель подключается тем же адресом, и tools работают как обычно:
Python
Схемы инструментов, tool_choice и цикл исполнения разобраны в разделе Вызов функций.

Структурированный вывод

Извлечение полей из найденного контекста — обычный запрос с response_format и JSON Schema: Структурированный вывод.

Генерация изображений

К RAG это отношения не имеет, но медиа-задачи создаются на SpeShu.AI отдельным эндпоинтом и не требуют Chroma: Создание задачи.

Частые проблемы

Проверьте адрес: должно быть https://speshu.ai/api/v1 — с /api и с /v1 на конце. Без суффикса /v1 клиент собирает путь /api/chat/completions и получает 404, хотя ключ при этом рабочий.
https://speshu.ai/api/v1/ — вариант хуже неправильного: часть клиентов склеивает его с путём и получает //chat/completions. Не пишите слэш в конце.
Ключ ушёл в клиент эмбеддингов, а не в генерацию, либо перепутан с ключом провайдера эмбеддингов. Это две разные переменные: SPESHU_API_KEY — только для SpeShu.AI.
Идентификатор модели зашит в код и разошёлся с каталогом. Возьмите его из GET /api/v1/models и держите в переменной SPESHU_MODEL. Подробности — в Ошибках.
Два сценария: коллекция заполнена векторами от одной модели эмбеддингов, а запрос идёт от другой; либо чанки добавлены с embeddings, а ищутся без них. Размерность векторов должна совпадать во всём пайплайне — пересчитайте коллекцию, если сменили модель эмбеддингов.
Поток включается параметром stream=True на chat.completions.create, отдельного эндпоинта для него нет. Формат кадров и разбор — в Потоковой передаче.
Полная таблица кодов и три формата ошибок API — на странице Ошибки.

Что дальше

Начало работы

Ключ, баланс и первый запрос целиком

Модели и цены

Как выбрать модель под задачу

Потоковая передача

SSE, [DONE] и кадр со списанием

Учёт средств

Как читать usage.cost.total_cost