> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-ru/rag-i-vektornye-bazy-dannykh/chromadb.md). # ChromaDB ChromaDB — это **ведущая векторная база данных с открытым исходным кодом** созданная специально для ИИ-приложений. Она предоставляет простой и интуитивно понятный API для хранения, запроса и управления высокоразмерными эмбеддингами — основой современных RAG-систем, семантического поиска, рекомендательных движков и памяти LLM. ChromaDB абстрагирует сложность векторного поиска по сходству, позволяя вам сосредоточиться на создании ИИ-приложений. Она поддерживает как режим in-memory для разработки, так и постоянный серверный режим для production-развертываний, с поддержкой Docker для простого развертывания на GPU-серверах Clore.ai. Ключевые возможности: * 🚀 **Простой API для Python/JavaScript** — начните за минуты * 💾 **Постоянное хранилище** — данные сохраняются после перезапуска контейнера * 🔍 **Несколько метрик расстояния** — косинусная, L2, скалярное произведение * 📦 **Интегрированные эмбеддинги** — встроенная поддержка OpenAI, Cohere, sentence-transformers * 🏗️ **Мультиарендность** — коллекции для организации разных наборов данных * 🔌 **REST API** — HTTP-интерфейс, не зависящий от языка * ⚡ **Быстро** — индекс HNSW для приближенного поиска ближайших соседей * 🔗 **Нативная поддержка LangChain/LlamaIndex** — интеграция первого класса {% hint style="success" %} Все примеры можно запускать на GPU-серверах, арендованных через [маркетплейс CLORE.AI](https://clore.ai/marketplace). {% endhint %} *** ## Требования к серверу | Параметр | Минимум | Рекомендуется | | -------- | ------------------------------ | ------------------------------------------- | | GPU | Любой NVIDIA GPU (опционально) | NVIDIA RTX 3080+ (для эмбеддингов) | | VRAM | Не требуется для ChromaDB | 8–16 ГБ (для локальных моделей эмбеддингов) | | ОЗУ | 4 ГБ | 16–32 ГБ | | CPU | 2 ядра | 8 ядер | | Диск | 10 ГБ | 50–200 ГБ (для больших наборов данных) | | ОС | Ubuntu 20.04+ | Ubuntu 22.04 | | Docker | Требуется | Docker + Docker Compose | | Порты | 22, 8000 | 22, 8000 | {% hint style="info" %} Сама ChromaDB не требует GPU — она эффективно работает на CPU. Однако, **генерация эмбеддингов** (преобразование текста в векторы) очень выигрывает от ускорения на GPU. Если вы планируете использовать локальные модели эмбеддингов (sentence-transformers и т. д.), выберите сервер с GPU. {% endhint %} *** ## Быстрое развертывание на CLORE.AI ### 1. Найдите подходящий сервер Перейдите на [маркетплейс CLORE.AI](https://clore.ai/marketplace) и выберите: * **только CPU** для сервера ChromaDB + API (хранение предварительно вычисленных эмбеддингов) * **GPU-сервер** если вы также хотите генерировать эмбеддинги локально ### 2. Настройте своё развёртывание **Docker-образ:** ``` chromadb/chroma:latest ``` **Сопоставление портов:** ``` 22 → доступ по SSH 8000 → HTTP API ChromaDB ``` **Переменные среды:** ``` IS_PERSISTENT=TRUE ANONYMIZED_TELEMETRY=FALSE CHROMA_SERVER_AUTH_CREDENTIALS_FILE=/chroma/auth.txt ``` **Команда запуска:** ```bash uvicorn chromadb.app:app --host 0.0.0.0 --port 8000 ``` ### 3. Проверьте развертывание ```bash curl http://:8000/api/v1/heartbeat # Ожидается: {"nanosecond heartbeat": } ``` *** ## Пошаговая настройка ### Шаг 1: Подключитесь к серверу по SSH ```bash ssh root@ -p ``` ### Шаг 2: Создайте каталог данных ```bash mkdir -p /workspace/chromadb/data mkdir -p /workspace/chromadb/config ``` ### Шаг 3: Запустите контейнер ChromaDB ```bash docker run -d \ --name chromadb \ -p 8000:8000 \\ -v /workspace/chromadb/data:/chroma/chroma \ -e IS_PERSISTENT=TRUE \ -e ANONYMIZED_TELEMETRY=FALSE \ -e CHROMA_SERVER_LOG_LEVEL=INFO \ chromadb/chroma:latest ``` ### Шаг 4: Проверьте, что он запущен ```bash # Проверить состояние curl http://localhost:8000/api/v1/heartbeat # Проверьте версию curl http://localhost:8000/api/v1/version # Список коллекций curl http://localhost:8000/api/v1/collections ``` ### Шаг 5: Установите Python-клиент ```bash pip install chromadb pip install sentence-transformers # Для локальных GPU-эмбеддингов pip install openai # Для эмбеддингов OpenAI ``` ### Шаг 6: Проверьте подключение из Python ```python import chromadb client = chromadb.HttpClient(host="", port=8000) print(f"Версия ChromaDB: {client.get_version()}") print(f"Пульс: {client.heartbeat()}") ``` ### Шаг 7: (Необязательно) Включите аутентификацию ```bash # Создайте учетные данные для аутентификации echo "admin:$2y$12$$(openssl rand -hex 16)" > /workspace/chromadb/auth.txt # Запустите с включенной аутентификацией docker run -d \ --name chromadb-auth \ -p 8000:8000 \\ -v /workspace/chromadb/data:/chroma/chroma \ -v /workspace/chromadb/auth.txt:/chroma/auth.txt \ -e IS_PERSISTENT=TRUE \ -e CHROMA_SERVER_AUTH_CREDENTIALS_FILE=/chroma/auth.txt \ -e CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER=chromadb.auth.providers.HtpasswdFileServerAuthCredentialsProvider \ -e CHROMA_SERVER_AUTH_PROVIDER=chromadb.auth.basic.BasicAuthServerProvider \ chromadb/chroma:latest ``` *** ## Примеры использования ### Пример 1: Базовые операции векторного хранилища ```python import chromadb from chromadb.utils import embedding_functions # Подключение к ChromaDB на сервере Clore.ai client = chromadb.HttpClient( host="<ваш-IP-сервера-Clore.ai>", port=8000 ) # Используйте sentence-transformers для эмбеддингов (работает на GPU, если доступно) embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction( model_name="all-MiniLM-L6-v2" ) # Создайте коллекцию collection = client.get_or_create_collection( name="clore_ai_docs", embedding_function=embedding_fn, metadata={"hnsw:space": "cosine"} # Метрика расстояния ) # Добавьте документы documents = [ "Clore.ai — это децентрализованный GPU-облачный маркетплейс для ИИ-нагрузок.", "На Clore.ai можно арендовать GPU NVIDIA RTX 4090, A100 и H100.", "Clore.ai поддерживает развертывания на базе Docker для любого ИИ-фреймворка.", "Цены на Clore.ai конкурентоспособны по сравнению с AWS и GCP.", "На маркетплейсе Clore.ai — тысячи GPU-серверов по всему миру.", "Вы можете развертывать PyTorch, TensorFlow, JAX и другие ML-фреймворки.", "Clore.ai предлагает спотовое ценообразование для экономичных GPU-вычислений.", ] ids = [f"doc_{i}" for i in range(len(documents))] collection.add( documents=documents, ids=ids, metadatas=[{"source": "docs", "index": i} for i in range(len(documents))] ) print(f"Добавлено {len(documents)} документов в коллекцию") print(f"Размер коллекции: {collection.count()} документов") ``` *** ### Пример 2: Семантический поиск ```python import chromadb from chromadb.utils import embedding_functions client = chromadb.HttpClient(host="", port=8000) embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction( model_name="all-MiniLM-L6-v2" ) collection = client.get_collection( name="clore_ai_docs", embedding_function=embedding_fn ) # Семантические поисковые запросы queries = [ "Сколько стоит аренда GPU?", "Какие инструменты машинного обучения доступны?", "Расскажите о вариантах GPU-оборудования", ] for query in queries: results = collection.query( query_texts=[query], n_results=3, include=["documents", "distances", "metadatas"] ) print(f"\n🔍 Запрос: {query}") for i, (doc, dist) in enumerate(zip( results["documents"][0], results["distances"][0] )): similarity = 1 - dist # Преобразуем расстояние в сходство print(f" {i+1}. [{similarity:.3f}] {doc[:100]}...") ``` *** ### Пример 3: RAG-пайплайн с ChromaDB + OpenAI ```python import chromadb from chromadb.utils import embedding_functions from openai import OpenAI # Инициализировать клиентов chroma_client = chromadb.HttpClient(host="", port=8000) openai_client = OpenAI(api_key="your-openai-api-key") # Используйте эмбеддинги OpenAI openai_ef = embedding_functions.OpenAIEmbeddingFunction( api_key="your-openai-api-key", model_name="text-embedding-3-small" ) # Получите коллекцию collection = chroma_client.get_or_create_collection( name="knowledge_base", embedding_function=openai_ef ) def add_to_knowledge_base(texts, ids=None, metadatas=None): """Добавить документы в базу знаний ChromaDB.""" if ids is None: ids = [f"doc_{i}" for i in range(len(texts))] collection.add(documents=texts, ids=ids, metadatas=metadatas or [{}]*len(texts)) print(f"✓ Добавлено {len(texts)} документов. Всего: {collection.count()}") def rag_query(question, n_context=5): """Извлеките релевантный контекст и сгенерируйте ответ с помощью GPT-4.""" # 1. Извлеките релевантные документы results = collection.query( query_texts=[question], n_results=n_context, include=["documents", "distances"] ) context_docs = results["documents"][0] distances = results["distances"][0] # 2. Сформируйте строку контекста context = "\n\n".join([ f"[Источник {i+1} (релевантность: {1-d:.2f})]: {doc}" for i, (doc, d) in enumerate(zip(context_docs, distances)) ]) # 3. Сгенерируйте ответ с помощью LLM messages = [ { "role": "system", "content": "Вы — полезный ассистент. Отвечайте на вопросы на основе предоставленного контекста. Если ответа нет в контексте, так и скажите." }, { "role": "user", "content": f"Контекст:\n{context}\n\nВопрос: {question}" } ] response = openai_client.chat.completions.create( model="gpt-4-turbo", messages=messages, temperature=0.1 ) answer = response.choices[0].message.content return { "question": question, "answer": answer, "sources": context_docs, "relevance_scores": [1 - d for d in distances] } # Пример использования knowledge = [ "Clore.ai — это GPU-облачный маркетплейс с более чем 45 000 пользователей.", "Clore.ai поддерживает развертывание нагрузок на базе Docker.", "GPU-серверы на Clore.ai варьируются от GTX 1080 до H100.", "Вы можете развертывать ИИ-приложения с доступом по SSH и пользовательскими портами.", ] add_to_knowledge_base(knowledge) result = rag_query("Сколько пользователей у Clore.ai?") print(f"В: {result['question']}") print(f"О: {result['answer']}") ``` *** ### Пример 4: Управление документами в нескольких коллекциях ```python import chromadb from chromadb.utils import embedding_functions client = chromadb.HttpClient(host="", port=8000) embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction( model_name="all-mpnet-base-v2" # Эмбеддинги более высокого качества ) # Создайте отдельные коллекции для разных типов документов collections = { "technical_docs": client.get_or_create_collection("technical_docs", embedding_function=embedding_fn), "faq": client.get_or_create_collection("faq", embedding_function=embedding_fn), "blog_posts": client.get_or_create_collection("blog_posts", embedding_function=embedding_fn), } # Добавьте документы в соответствующие коллекции collections["technical_docs"].add( documents=["Руководство по развертыванию Docker для Clore.ai", "Настройка SSH для GPU-серверов"], ids=["tech_001", "tech_002"], metadatas=[{"type": "руководство", "version": "v2"}, {"type": "конфигурация"}] ) collections["faq"].add( documents=["В: Как мне оплатить? О: С помощью криптовалюты.", "В: Какие GPU? О: От RTX до H100."], ids=["faq_001", "faq_002"], metadatas=[{"category": "платежи"}, {"category": "оборудование"}] ) # Выполните поиск по всем коллекциям def search_all_collections(query, n_results=2): all_results = [] for name, col in collections.items(): results = col.query(query_texts=[query], n_results=n_results) for doc, dist in zip(results["documents"][0], results["distances"][0]): all_results.append({ "collection": name, "document": doc, "similarity": 1 - dist }) # Отсортируйте по релевантности all_results.sort(key=lambda x: x["similarity"], reverse=True) return all_results[:n_results * 2] results = search_all_collections("Как развернуть с Docker?") for r in results: print(f"[{r['collection']}] ({r['similarity']:.3f}) {r['document'][:80]}...") ``` *** ### Пример 5: Фильтрация и запросы по метаданным ```python import chromadb client = chromadb.HttpClient(host="", port=8000) collection = client.get_collection("technical_docs") # Добавьте документы с подробными метаданными collection.add( documents=[ "Руководство: запуск PyTorch на GPU-кластерах NVIDIA A100", "Руководство: распределенное обучение TensorFlow на RTX 4090", "Учебное пособие: тонкая настройка LLM с LoRA на GPU", "Справка: матрица совместимости CUDA 12.1", "Руководство: Docker-сеть для конфигураций с несколькими GPU", ], ids=["d1", "d2", "d3", "d4", "d5"], metadatas=[ {"type": "руководство", "gpu": "A100", "framework": "pytorch", "year": 2024}, {"type": "руководство", "gpu": "RTX4090", "framework": "tensorflow", "year": 2024}, {"type": "учебное пособие", "gpu": "любой", "framework": "transformers", "year": 2024}, {"type": "справка", "gpu": "любой", "framework": "cuda", "year": 2023}, {"type": "руководство", "gpu": "несколько", "framework": "docker", "year": 2024}, ] ) # Запрос с фильтром по метаданным results = collection.query( query_texts=["Руководство по обучению на GPU"], n_results=3, where={"type": "руководство"}, # Только руководства include=["documents", "metadatas", "distances"] ) print("Отфильтрованные результаты (type=guide):") for doc, meta, dist in zip( results["documents"][0], results["metadatas"][0], results["distances"][0] ): print(f" [{1-dist:.3f}] {doc}") print(f" Метаданные: {meta}") ``` *** ## Конфигурация ### Docker Compose (продакшн) ```yaml version: '3.8' services: chromadb: image: chromadb/chroma:latest container_name: chromadb ports: - "8000:8000" volumes: - chromadb_data:/chroma/chroma environment: - IS_PERSISTENT=TRUE - ANONYMIZED_TELEMETRY=FALSE - CHROMA_SERVER_LOG_LEVEL=INFO - ALLOW_RESET=FALSE - CHROMA_SEGMENT_CACHE_POLICY=LRU - CHROMA_MEMORY_LIMIT_BYTES=2147483648 # кэш 2 ГБ restart: unless-stopped healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/heartbeat"] interval: 30s timeout: 10s retries: 3 volumes: chromadb_data: driver: local ``` ### Справочник по переменным окружения | Переменная | По умолчанию | Описание | | ----------------------------- | ------------ | -------------------------------------------- | | `IS_PERSISTENT` | `FALSE` | Включить постоянное хранилище | | `ANONYMIZED_TELEMETRY` | `TRUE` | Отключить сбор статистики использования | | `CHROMA_SERVER_LOG_LEVEL` | `INFO` | Подробность логов | | `CHROMA_MEMORY_LIMIT_BYTES` | Нет | Максимальный объем памяти для кэша сегментов | | `ALLOW_RESET` | `FALSE` | Разрешить сброс всех данных через API | | `CHROMA_SERVER_AUTH_PROVIDER` | Нет | Класс провайдера аутентификации | *** ## Советы по производительности ### 1. Выберите подходящую модель эмбеддингов | Модель | Размерность | Скорость | Качество | Требуется GPU | | ------------------------ | ----------- | -------- | ----------- | ---------------- | | `all-MiniLM-L6-v2` | 384 | Быстро | Хорошо | Нет | | `all-mpnet-base-v2` | 768 | Средняя | Лучше | Необязательно | | `text-embedding-3-small` | 1536 | Быстро | Отлично | Только через API | | `BAAI/bge-large-en-v1.5` | 1024 | Средняя | Лучше всего | Да | ### 2. Пакетные upsert-операции для скорости ```python # Добавляйте пакетами по 100–1000 для лучшей производительности BATCH_SIZE = 500 for i in range(0, len(all_documents), BATCH_SIZE): batch = all_documents[i:i+BATCH_SIZE] collection.add( documents=[d["text"] for d in batch], ids=[d["id"] for d in batch], metadatas=[d["meta"] for d in batch] ) print(f"Пакет {i//BATCH_SIZE + 1} завершён") ``` ### 3. Настройка индекса HNSW ```python collection = client.create_collection( name="optimized", metadata={ "hnsw:space": "cosine", "hnsw:construction_ef": 200, # Чем выше, тем лучше качество индекса (медленнее построение) "hnsw:search_ef": 100, # Чем выше, тем лучше полнота (медленнее поиск) "hnsw:M": 32, # Чем выше, тем лучше полнота (больше памяти) } ) ``` ### 4. Постоянный клиент для локального использования ```python # Для разработки напрямую на сервере Clore.ai import chromadb client = chromadb.PersistentClient(path="/workspace/chromadb/data") # Сервер не нужен, быстрее для однопроцессного использования ``` *** ## Устранение неполадок ### Проблема: не удается подключиться к ChromaDB ```bash # Проверьте, что контейнер запущен docker ps | grep chromadb # Проверьте логи docker logs chromadb --tail 20 # Проверьте изнутри контейнера docker exec chromadb curl http://localhost:8000/api/v1/heartbeat ``` ### Проблема: данные теряются после перезапуска контейнера ```bash # Убедитесь, что том подключен docker inspect chromadb | grep Mounts -A 10 # Повторно запустите с явным указанием тома docker run -d -p 8000:8000 \ -v /workspace/chromadb/data:/chroma/chroma \ -e IS_PERSISTENT=TRUE \ chromadb/chroma:latest ``` ### Проблема: ошибки нехватки памяти ```bash # Ограничьте кэш памяти docker run -d -p 8000:8000 \ -e CHROMA_MEMORY_LIMIT_BYTES=1073741824 \ -v /workspace/chromadb/data:/chroma/chroma \ chromadb/chroma:latest ``` ### Проблема: медленная генерация эмбеддингов ```bash # Проверьте, что для embeddings используется GPU python3 -c " import torch from sentence_transformers import SentenceTransformer model = SentenceTransformer('all-MiniLM-L6-v2', device='cuda') print(f'Embedding model on: {model.device}') " ``` ### Проблема: коллекция не найдена после перезапуска ```bash # Проверьте, что постоянное хранение включено curl http://localhost:8000/api/v1/collections # Если пусто, IS_PERSISTENT не был задан или том не был подключён ``` *** ## Ссылки * **GitHub**: * **Официальная документация**: * **Docker Hub**: * **PyPI**: * **Discord**: * **маркетплейс CLORE.AI**: *** ## Рекомендации по GPU для Clore.ai | Сценарий использования | Рекомендуемый GPU | Оценочная стоимость на Clore.ai | | ------------------------------------------------------- | ----------------- | ------------------------------- | | Разработка/тестирование | RTX 3090 (24 ГБ) | $0.07–0.21/гпу/ч | | RAG для продакшена | RTX 3090 (24 ГБ) | $0.07–0.21/гпу/ч | | Генерация эмбеддингов с высокой пропускной способностью | RTX 4090 (24 ГБ) | $0.14–0.42/гпу/ч | > 💡 Все примеры в этом руководстве можно развернуть на [Clore.ai](https://clore.ai/marketplace) GPU-серверах. Просматривайте доступные GPU и арендуйте по часам — без обязательств, с полным root-доступом. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.clore.ai/guides/guides_v2-ru/rag-i-vektornye-bazy-dannykh/chromadb.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.