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) подключаются одним аргументом.Установка
1
Установите пакеты
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.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: Создание задачи.Частые проблемы
404 на запросе к модели
404 на запросе к модели
Проверьте адрес: должно быть
https://speshu.ai/api/v1 — с /api и с /v1 на конце. Без суффикса /v1 клиент собирает путь /api/chat/completions и получает 404, хотя ключ при этом рабочий.Адрес задан с лишним слэшем в конце
Адрес задан с лишним слэшем в конце
https://speshu.ai/api/v1/ — вариант хуже неправильного: часть клиентов склеивает его с путём и получает //chat/completions. Не пишите слэш в конце.401 invalid_api_key при рабочем Chroma
401 invalid_api_key при рабочем Chroma
Ключ ушёл в клиент эмбеддингов, а не в генерацию, либо перепутан с ключом провайдера эмбеддингов. Это две разные переменные:
SPESHU_API_KEY — только для SpeShu.AI.404 model_not_found на первом же чате
404 model_not_found на первом же чате
Идентификатор модели зашит в код и разошёлся с каталогом. Возьмите его из
GET /api/v1/models и держите в переменной SPESHU_MODEL. Подробности — в Ошибках.Поиск возвращает пустой результат или dimension mismatch
Поиск возвращает пустой результат или dimension mismatch
Два сценария: коллекция заполнена векторами от одной модели эмбеддингов, а запрос идёт от другой; либо чанки добавлены с
embeddings, а ищутся без них. Размерность векторов должна совпадать во всём пайплайне — пересчитайте коллекцию, если сменили модель эмбеддингов.404 при попытке включить поток
404 при попытке включить поток
Поток включается параметром
stream=True на chat.completions.create, отдельного эндпоинта для него нет. Формат кадров и разбор — в Потоковой передаче.Всё остальное
Всё остальное
Полная таблица кодов и три формата ошибок API — на странице Ошибки.
Что дальше
Начало работы
Ключ, баланс и первый запрос целиком
Модели и цены
Как выбрать модель под задачу
Потоковая передача
SSE,
[DONE] и кадр со списаниемУчёт средств
Как читать
usage.cost.total_cost