Как развернуть RAG-систему с Chroma (векторная БД)

После выполнения инструкции у вас будет рабочий retrieval-контур для RAG на Chroma: коллекция с чанками документов, постоянное хранение на диске или отдельный локальный сервер, тестовый запрос на поиск релевантных фрагментов и понятная точка передачи найденного контекста в LLM.

Практический вердикт: если вы разворачиваете RAG внутри одного Python-приложения, начинайте с PersistentClient. Если retrieval нужен как отдельный сервис для нескольких процессов или приложений, используйте chroma run --path ... и HttpClient. Для managed production у Chroma есть Cloud с теми же API, но регионы, цены и лимиты стоит перепроверять прямо перед внедрением.

Что вы развернёте

Официальный retrieval flow у Chroma такой: встроить базу знаний в embeddings, сохранить её в Chroma, встроить пользовательский запрос, извлечь подходящие чанки и передать найденный текст вместе с исходным запросом в LLM. В этой инструкции вы поднимете именно retrieval-слой и точку передачи контекста дальше в генерацию.

Chroma — open-source инфраструктура данных для AI под Apache 2.0. По документации она поддерживает хранение embeddings с metadata, dense, sparse и hybrid search, full-text и regex search, metadata filtering и multimodal retrieval. Если хотите освежить термин, см. RAG (Retrieval-Augmented Generation).

Пошаговое развёртывание

1. Шаг 1. Установите пакет chromadb

   Установите официальный Python-клиент Chroma в вашей рабочей среде.

   pip install chromadb

   Ожидаемый результат: модуль chromadb доступен для импорта в Python.

2. Шаг 2. Включите постоянное хранение вместо временной памяти

   Не начинайте с chromadb.Client(), если вам нужно сохранять индекс между перезапусками. Официальный quickstart указывает, что этот in-memory клиент временный и данные теряются после завершения программы. Для локального приложения используйте PersistentClient.

   import chromadb
   
   client = chromadb.PersistentClient(path='./chroma-data')

   Ожидаемый результат: данные будут писаться в каталог ./chroma-data, а не жить только в памяти текущего процесса.

3. Шаг 3. Запустите отдельный локальный сервер, если retrieval нужен нескольким процессам

   Этот шаг нужен, если Chroma должен работать как самостоятельный сервис. Если вам достаточно PersistentClient внутри одного приложения, шаг можно пропустить.

   chroma run --path ./chroma-data

   По документации локальный сервер по умолчанию слушает localhost на порту 8000. Подключение клиента выглядит так:

   import chromadb
   
   client = chromadb.HttpClient(host='localhost', port=8000)

   Ожидаемый результат: сервис запущен, а клиент знает, куда к нему обращаться.

4. Шаг 4. Создайте коллекцию и загрузите в неё чанки документов

   Добавляйте в коллекцию не целые длинные файлы, а небольшие смысловые фрагменты. В проверенном пакете источников не зафиксирован универсальный размер чанка, поэтому режьте документы по логическим блокам и проверяйте качество retrieval на своих данных.

   collection = client.get_or_create_collection(name='kb')
   
   collection.add(
       ids=['chunk-1', 'chunk-2', 'chunk-3'],
       documents=[
           'Chroma stores embeddings and metadata for AI retrieval.',
           'RAG retrieves matching chunks and passes them to the LLM.',
           'PersistentClient or server mode keeps data beyond one process.'
       ],
       metadatas=[
           {'section': 'intro'},
           {'section': 'retrieval'},
           {'section': 'persistence'}
       ]
   )
   
   print(collection.count())

   Python Collection API документирует add для вставки записей и count для проверки общего количества. Ожидаемый результат: count() возвращает число больше нуля.

5. Шаг 5. Выполните тестовый retrieval-запрос

   Для ближайших соседей используйте query. В Python можно передать query_texts; по документации этот параметр использует embedding function коллекции, если она задана. В TypeScript-примерах имя может отличаться и выглядеть как queryTexts.

   results = collection.query(
       query_texts=['How do I keep my Chroma data after restart?'],
       n_results=2
   )
   
   print(results)

   Ожидаемый результат: в выдаче есть чанк про PersistentClient или server mode, то есть Chroma возвращает релевантный контекст, а не случайный фрагмент.

6. Шаг 6. Передайте найденный контекст в LLM-слой

   Официальный flow Chroma завершает retrieval на том, что вы передаёте найденный текст вместе с исходным вопросом в LLM. Со стороны векторной БД этого достаточно для минимального RAG-контура.

   question = 'How do I keep my Chroma data after restart?'
   context = results['documents']
   
   # Pass question + context to your RAG, agent or LLM layer.

   Редакционное ограничение: в проверенном пакете источников не подтверждён конкретный SDK LLM, prompt template или orchestrator. Поэтому эта инструкция воспроизводимо разворачивает retrieval-слой Chroma и фиксирует точку передачи контекста дальше в ваш стек, но не навязывает интеграцию с конкретным генератором.

Как проверить, что всё работает

Проверяйте развёртывание тремя независимыми способами, а не только тем, что код не упал с ошибкой.

• Проверьте доступность клиента: выполните client.heartbeat(). Документация указывает, что метод возвращает timestamp в наносекундах; в server mode этот же health-check доступен по GET /api/v2/heartbeat.
• Проверьте наличие данных: выполните collection.count() и убедитесь, что число равно количеству загруженных записей.
• Проверьте качество retrieval: выполните тестовый query по вопросу, ответ на который явно есть в ваших чанках. Если выдача нерелевантна, сначала пересоберите чанки и только потом меняйте слой генерации.

print(client.heartbeat())
print(collection.count())
print(results)

Для дополнительной инспекции Python API также документирует peek и get, что удобно для просмотра содержимого коллекции и фильтрации по metadata.

Частые ошибки и исправления

• ❌ Ошибка: после перезапуска программы данные исчезли.
  ✅ Решение: вы, вероятно, использовали chromadb.Client() из quickstart-демо. Он временный. Переключитесь на PersistentClient или на client-server mode.
• ❌ Ошибка: клиент не может подключиться к локальному серверу.
  ✅ Решение: проверьте, что процесс запущен командой chroma run --path ..., а клиент подключается к host='localhost' и port=8000, если вы не меняли значения по умолчанию.
• ❌ Ошибка: пример из Python не совпадает с TypeScript-кодом.
  ✅ Решение: это ожидаемо. В официальных материалах названия методов могут немного отличаться по binding, например query_texts в Python и queryTexts в TypeScript.
• ❌ Ошибка: в Chroma Cloud документ или embedding не принимается.
  ✅ Решение: проверьте лимиты: максимальная размерность embeddings — 4096, размер документа — 16384 bytes.
• ❌ Ошибка: вы ожидаете очень большую выдачу из одного запроса в Cloud.
  ✅ Решение: перепроверьте лимит на максимальное число возвращаемых результатов: по документации это 300.

Безопасность и ограничения

У Chroma есть open-source и managed-варианты. Open-source версия распространяется под Apache 2.0, но при self-hosted развёртывании операционные задачи остаются на вас: хостинг, диск, резервные копии, обновления и security hardening.

Chroma Cloud — serverless-сервис с теми же API, что и open-source Chroma. По документации базы данных остаются в выбранном регионе; для multi-tenant deployment сейчас задокументированы AWS us-east-1 и GCP europe-west1. Single-tenant и BYOC доступны через обращение в Chroma.

Cloud использует usage-based pricing. На момент проверки официальная страница указывает: writes — $2.50 за logical GiB, reads — $0.0075 за TiB queried и $0.09 за GiB returned, storage — $0.33 за GiB в месяц, forking — $0.03 за один fork request, новым пользователям задокументированы $5 credits. Это именно операционные условия, поэтому перепроверьте их ещё раз перед оплатой или production rollout.

Cloud-лимиты, которые стоит сверить заранее: максимальная размерность embeddings — 4096, максимальный размер документа — 16384 bytes, максимальное число возвращаемых результатов — 300, maximum collections — 1000000, maximum records per collection — 5000000.

Практическое ограничение этой инструкции: она закрывает развёртывание retrieval-слоя Chroma и валидацию поиска, но не фиксирует конкретный embedding model, размер чанков или LLM SDK, потому что такие детали не были подтверждены в проверенном наборе официальных источников для этой публикации.

Что делать дальше

• Если нужен более широкий blueprint всей системы, перейдите к инструкции Как собрать RAG-систему: пошагово.
• Если вы строите orchestration поверх индексатора и query engine, посмотрите Как настроить RAG с LlamaIndex.
• Если retrieval уже готов, а модели ещё нет, разверните собственную генерацию по гайду Как развернуть open-source LLM на сервере.
• Если выбираете векторную БД между несколькими вариантами, сравните подходы в материале Как настроить векторную базу: Pinecone и Chroma.

Источники

• Introduction – Chroma Docs
• Getting Started – Chroma Docs
• Intro to Retrieval – Chroma Docs
• Chroma Clients – Chroma Docs
• Run a Chroma Server – Chroma Docs
• Collection – Chroma Docs
• Heartbeat – Chroma Docs
• Chroma Cloud – Chroma Docs
• Pricing – Chroma Docs
• Quotas & Limits – Chroma Docs
• Releases · chroma-core/chroma · GitHub
• GitHub – chroma-core/chroma: Search infrastructure for AI · GitHub

Вопросы и ответы

Можно ли развернуть Chroma без отдельного сервера?

Да. Для локального приложения достаточно PersistentClient. Отдельный сервер через chroma run нужен, когда retrieval должен обслуживать несколько процессов или приложений.

Почему не стоит начинать с chromadb.Client()?

Потому что официальный quickstart описывает его как in-memory клиент: после завершения программы данные теряются. Для реального RAG даже на локальной машине обычно нужен PersistentClient или client-server mode.

Подходит ли Chroma Cloud для production?

Да, документация описывает Chroma Cloud как hosted, serverless-сервис с теми же API, что и open-source Chroma. Но перед запуском перепроверьте регионы, квоты, лимиты и цены, потому что это операционные условия.

Почему в примерах встречаются query_texts и queryTexts?

Это различие между language bindings. В проверенных источниках отдельно отмечено, что имена методов могут немного отличаться между Python и TypeScript.

Какие лимиты важнее всего проверить перед production rollout в Cloud?

По официальной странице Cloud limits сначала проверьте максимальную размерность embeddings 4096, размер документа 16384 bytes и максимальное число возвращаемых результатов 300. Эти ограничения чаще всего влияют на ingest и retrieval.