Содержание
  1. Что хранит коллекция
  2. Готовые векторы и embeddingfunction
  3. Get и query
  4. Полный учебный fixture
  5. Фильтр и пустой результат
  6. Сохранение данных
  7. Что проверить перед подключением
  8. Частые вопросы
Обзоры

Обзор Chroma: коллекции и поиск по готовым векторам

16 ноября 2026 · 12 минут чтения

Обзор Chroma: коллекции и поиск по готовым векторам — это разбор того, как в Chroma хранятся ID, документы, метаданные и эмбеддинги, чем query отличается от get и как проверить поиск на заранее известных векторах. Ниже — учебный набор из трёх записей, эталонные расстояния и порядок проверки результата.

Что хранит коллекция

Коллекция в Chroma — контейнер для записей, у каждой из которых есть идентификатор, документ, метаданные и вектор. Документация проекта на docs.trychroma.com описывает назначение так: Chroma даёт всё нужное для поиска — хранит эмбеддинги с метаданными, ищет по плотным и разреженным векторам, фильтрует по метаданным и извлекает данные из текста, изображений и других типов. Конкретную метрику и параметры индекса проверяют в конфигурации коллекции.

Идентификатор обязателен. В разделе getting-started документации сказано, что для документов нужно предоставить уникальные строковые ID. Практический вывод: строка a, b, c подходит, поведение при повторе ID зависит от операции. Текущая документация .add прямо говорит: уже существующий ID игнорируется без исключения; для изменения данных используют соответствующие методы обновления.

Метаданные — словарь с парами ключ-значение. В учебном наборе это {kind: help} и {kind: archive}. Метаданные участвуют в фильтрации и не влияют на расстояние между векторами. Документ — текстовая нагрузка записи, которую вы возвращаете читателю после поиска. Вектор — числовой массив, по которому считается близость.

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

Поле записи Обязательность Роль в поиске
ID Обязательно Ключ записи, возвращается в результатах
Document По сценарию Текстовая нагрузка, отдаётся читателю
Metadata По сценарию Основа для фильтра, в расстояние не входит
Embedding По сценарию Вектор для сравнения близости

Коллекция живёт внутри клиента. Клиент определяет, где хранятся данные: в памяти процесса, в локальной папке или на сервере. От этого выбора зависит сохранение между запусками, и об этом ниже отдельный раздел.

Готовые векторы и embeddingfunction

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

Полный учебный набор:

  • ID a, документ «инструкция возврата», метаданные {kind: help}, вектор [1, 0];
  • ID b, документ «оформление», метаданные {kind: help}, вектор [0, 1];
  • ID c, документ «архив», метаданные {kind: archive}, вектор [-1, 0].

Все три вектора — ручные учебные значения. Векторы заданы для проверки механики; семантическое качество модели ими не измерялось. Такой набор хорош тем, что расстояния считаются в уме и результат поиска можно сверить без внешнего сервиса.

PYTHON2 строки
import chromadb
client = chromadb.EphemeralClient()

Затем создайте в этом клиенте коллекцию help_center с явно выбранной cosine по актуальной документации вашей версии. Ниже имя collection означает уже настроенную коллекцию. Старый параметр metadata={"hnsw:space": "cosine"} из сторонних руководств здесь не используется как готовая текущая команда. Перед добавлением записей проверьте фактическую конфигурацию.

PYTHON6 строк
collection.add(
    ids=["a", "b", "c"],
    documents=["инструкция возврата", "оформление", "архив"],
    metadatas=[{"kind": "help"}, {"kind": "help"}, {"kind": "archive"}],
    embeddings=[[1.0, 0.0], [0.0, 1.0], [-1.0, 0.0]],
)

Параметр метрики в примере задан явно. Если продукт вернёт L2 вместо cosine, разницу нельзя записывать в вычислительную ошибку: сначала проверьте конфигурацию метрики, потом повторяйте тест. Синтаксис создания коллекции и имя параметра метрики сверяйте с текущей документацией проекта, потому что старые статьи могут описывать прежний интерфейс.

Embedding-функция полезна, когда тексты приходят потоком и вы не хотите считать векторы вручную. Тогда документы передаются без embeddings, а коллекция получает функцию при создании. Для отладки поиска ручные векторы остаются удобнее: они убирают из уравнения модель и оставляют только механику индекса.

Get и query

Два метода отвечают на разные вопросы. Документация проекта разводит их так: Query API выполняет поиск ближайших соседей по плотным эмбеддингам, а Get API служит для извлечения записей без ранжирования по близости. Отсюда практическое правило: нужен конкретный документ по ID — берите get, нужны похожие записи — берите query.

Запрос к учебной коллекции:

PYTHON7 строк
result = collection.query(
    query_embeddings=[[1.0, 0.0]],
    n_results=3,
)

print(result["ids"])
print(result["distances"])

Ожидаемый порядок при cosine: сначала a с расстоянием 0, затем b с расстоянием 1, затем c с расстоянием 2. Расстояние cosine — это единица минус косинусная близость двух векторов, как объясняет статья на realpython.com. Для вектора [1, 0] запроса запись a совпадает по направлению, b ортогональна, c направлена противоположно.

Форма ответа важна при разборе. Документация описывает результаты .query и .get как массивы по полям, но их вложенность различается. Для .query поле result["ids"] содержит список списков: внешний уровень соответствует запросам, внутренний — найденным записям. Для .get поле ids содержит плоский список идентификаторов. Проверяйте форму конкретного метода перед обращением по индексу.

Метод Что делает Когда применять
query Ищет ближайших соседей Похожие документы по вектору
get Возвращает записи по ID или фильтру Известен ID или нужен срез по метаданным

Get по ID b выбирает конкретную запись без поиска соседей. Это ключевая проверка: если get возвращает a, значит вы перепутали метод или передали не тот ключ. Размерность вектора запроса должна совпадать с размерностью векторов коллекции — документация называет это отдельным требованием.

Полный учебный fixture

Соберём самостоятельный вычислительный эталон, чтобы отделить арифметику от настройки клиента и индекса. Для проверки задан авторский учебный набор; продуктовые результаты здесь не измерялись. Внешний сервис не запускался, модель не обучалась, скорость не замерялась.

PYTHON28 строк
from math import sqrt

records = {
    "a": {"document": "инструкция возврата", "kind": "help", "vector": [1, 0]},
    "b": {"document": "оформление", "kind": "help", "vector": [0, 1]},
    "c": {"document": "архив", "kind": "archive", "vector": [-1, 0]},
}
query_vector = [1, 0]

def cosine_distance(left, right):
    dot = sum(a * b for a, b in zip(left, right))
    left_norm = sqrt(sum(a * a for a in left))
    right_norm = sqrt(sum(b * b for b in right))
    return 1 - dot / (left_norm * right_norm)

def expected(kind=None):
    candidates = [
        (key, cosine_distance(row["vector"], query_vector))
        for key, row in records.items()
        if kind is None or row["kind"] == kind
    ]
    return sorted(candidates, key=lambda item: item[1])

assert expected() == [("a", 0), ("b", 1), ("c", 2)]
assert expected("help") == [("a", 0), ("b", 1)]
assert expected("missing") == []
assert records["b"]["document"] == "оформление"
print(expected())

Этот самостоятельный код вычисляет эталон стандартной библиотекой Python. Он не запускает Chroma: сравните его результат с query своей настроенной коллекции, а получение записи b проверьте через collection.get(ids=["b"]). Для указанных ненулевых двумерных векторов расстояния определены; нулевые векторы потребовали бы отдельной политики.

Порядок действий для читателя:

  1. Создайте клиент и коллекцию с явной метрикой.
  2. Добавьте три записи с ручными векторами.
  3. Выполните query с вектором [1, 0] и числом соседей 3.
  4. Сверьте порядок ID с эталоном a, b, c.
  5. Выполните get по ID b и убедитесь, что вернулась одна запись.
  6. Повторите query с фильтром и проверьте сужение набора.

Эталон расстояний: a — 0, b — 1, c — 2. Порядок a, b, c держится на этих числах. Если продукт выдаёт другой порядок при явно заданной cosine, проверьте конфигурацию метрики, размерность и сохранённые векторы; модель эмбеддингов в этой проверке не участвует.

Учебный результат сверяется с заданным входом. Параметры продукта сверяются с текущей документацией. Эти две проверки независимы, и смешивать их не стоит: fixture подтверждает, что вы понимаете механику, документация подтверждает, что вызовы соответствуют вашей версии пакета.

Фильтр и пустой результат

Фильтр по метаданным сужает набор до записей, у которых поле совпадает со значением. В учебном наборе kind=help оставляет a и b, а kind=archive оставляет c. Фильтр применяется до ранжирования, поэтому в результатах остаются только подходящие записи, отсортированные по близости.

PYTHON6 строк
filtered = collection.query(
    query_embeddings=[[1.0, 0.0]],
    n_results=3,
    where={"kind": "help"},
)
print(filtered["ids"])

Ожидаемый результат — a, затем b. Запись c отсечена по метаданным, хотя её вектор и лежит в коллекции. Полезно проверить и обратный случай: where={"kind": "missing"} даёт пустой набор. Пустой результат — нормальный ответ на фильтр, который ни с чем не совпал.

Пустой набор приходит в той же column-major форме: внешний список содержит один запрос, внутренний пуст. Код, который берёт result["ids"][0][0] без проверки длины, упадёт с ошибкой индекса. Обрабатывайте пустоту явно: проверяйте длину внутреннего списка перед обращением к первому элементу.

Фильтр Остаются Порядок по близости
Без фильтра a, b, c a, b, c
kind=help a, b a, b
kind=archive c c
kind=missing пусто —

Фильтр по метаданным работает и в get: метод вернёт все записи, подходящие под условие, без ранжирования. Это удобно для инвентаризации: посчитать, сколько записей помечено help, можно через get с фильтром, не прибегая к векторному поиску.

Сохранение данных

Клиент определяет, переживут ли данные перезапуск программы. Документация getting-started описывает поведение по умолчанию: стартует Chroma-сервер в памяти, и все загруженные данные теряются при завершении программы. Временный клиент по определению не обеспечивает сохранение между процессами.

DataCamp в своём руководстве показывает отдельный путь для тестов: временную базу в памяти можно создать через chromadb.EphemeralClient(). Такой клиент удобен для учебных прогонов и проверок, где данные нужны только на время работы скрипта.

Для сохранения между запусками клиент и путь задаются явно. Порядок проверки:

  1. Создайте клиент с постоянным путём или адресом сервера.
  2. Добавьте записи и завершите программу.
  3. Запустите программу снова с тем же клиентом и путём.
  4. Выполните get по известному ID.
  5. Сверьте документ и метаданные с тем, что добавляли.

Частая ошибка — перепутать новую пустую коллекцию с пропажей данных. Если после перезапуска коллекция пуста, проверьте, что клиент и путь совпадают с прошлым запуском, а имя коллекции записано точно. Новая коллекция с тем же именем на другом пути будет пустой, и это ожидаемо.

DataCamp также отмечает, что при вызове collection.update() можно передать только ids и metadatas, опустив documents и embeddings. Это удобно для правки метаданных без пересчёта векторов. Поведение update стоит сверить с текущей документацией проекта перед применением в рабочем коде.

Что проверить перед подключением

Перед реальным вызовом API пройдите короткий чек-лист. Он экономит время на отладке и отделяет ошибки конфигурации от ошибок логики.

  • Версия пакета и синтаксис создания коллекции. Сверьте с текущей документацией проекта, потому что параметры метрики и имена полей менялись между версиями.
  • Метрика расстояния. Задайте её явно и проверьте, что продукт использует именно cosine, если вы считаете эталон по cosine.
  • Размерность векторов. Длина массива при добавлении и при запросе должна совпадать с размерностью коллекции.
  • Режим клиента. Временный клиент теряет данные при завершении, постоянный сохраняет. Выберите режим под задачу.
  • Уникальность ID. Поведение повторных ID зависит от операции: текущая документация .add описывает игнорирование существующего ID без исключения; изменение записи выполняют методом обновления.
  • Форма ответа. Результаты приходят массивами по полям, обращение к первому элементу требует проверки длины.
  • Обработка пустого результата. Фильтр без совпадений возвращает пустой набор, и код должен это выдерживать.

Лицензия проекта — Apache 2.0, как указано в документации. Это важно при встраивании Chroma в продукт: условия лицензии стоит прочитать до релиза.

Отдельно про метрику. Real Python в своём руководстве объясняет, что приближённый поиск ближайших соседей не гарантирует максимальную близость к запросу: индекс рекомендует эмбеддинги, и результат может отличаться от полного перебора. Для учебного набора из трёх записей это несущественно, а на больших коллекциях стоит держать в голове.

Частые вопросы

Что такое ChromaDB простыми словами?

Chroma — это хранилище векторов с метаданными и документами, поверх которого работает поиск похожих записей. Документация проекта описывает её как набор средств для извлечения: хранение эмбеддингов с метаданными, поиск по плотным и разреженным векторам, фильтрация по метаданным. Вы добавляете записи, а затем ищете ближайшие к вектору запроса. Лицензия — Apache 2.0.

Как установить ChromaDB на Python?

Пакет ставится через pip, после чего в коде создаётся клиент и коллекция. Документация getting-started приводит pip install chromadb; устанавливайте пакет в отдельное окружение и фиксируйте версию. Для учебных прогонов удобен временный клиент в памяти. Для сохранения данных задайте постоянный путь или адрес сервера явно.

Чем query отличается от get?

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

Почему фильтр возвращает пустой результат?

Фильтр оставляет записи, у которых поле метаданных совпадает со значением. Если ни одна запись не подходит, набор пуст, и это нормальный ответ. Проверьте точное написание ключа и значения: help и Help — разные строки. Обрабатывайте пустоту в коде явно, проверяя длину внутреннего списка перед обращением к первому элементу.

Как сохранить данные между запусками?

Задайте клиент с постоянным путём или адресом сервера при создании. Временный клиент стартует сервер в памяти, и данные теряются при завершении программы. После перезапуска выполните get по известному ID и сверьте документ с тем, что добавляли. Если коллекция пуста, проверьте режим клиента, путь, сервер и точное имя коллекции; частота таких причин здесь не измерялась.

Читайте также

3 материала