> 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-es/rag-y-bases-de-datos-vectoriales/chromadb.md). # ChromaDB Despliega la base de datos vectorial de código abierto ChromaDB para aplicaciones de IA en las GPU de Clore.ai ChromaDB es la **la base de datos vectorial de código abierto líder** diseñada específicamente para aplicaciones de IA. Proporciona una API simple e intuitiva para almacenar, consultar y gestionar embeddings de alta dimensión — la base de los sistemas RAG modernos, la búsqueda semántica, los motores de recomendación y la memoria de LLM. ChromaDB abstrae la complejidad de la búsqueda por similitud vectorial, permitiéndote centrarte en crear aplicaciones de IA. Admite tanto el modo en memoria para desarrollo como un modo de servidor persistente para despliegues en producción, con soporte de Docker para una implementación sencilla en servidores GPU de Clore.ai. Características principales: * 🚀 **API simple de Python/JavaScript** — comienza en minutos * 💾 **Almacenamiento persistente** — los datos sobreviven a los reinicios del contenedor * 🔍 **Múltiples métricas de distancia** — coseno, L2, producto interno * 📦 **Embeddings integrados** — soporte integrado para OpenAI, Cohere, sentence-transformers * 🏗️ **Multiinquilino** — colecciones para organizar diferentes conjuntos de datos * 🔌 **API REST** — interfaz HTTP agnóstica del lenguaje * ⚡ **Rápido** — índice HNSW para búsqueda aproximada de vecinos más cercanos * 🔗 **Nativo de LangChain/LlamaIndex** — integración de primera clase {% hint style="success" %} Todos los ejemplos se pueden ejecutar en servidores GPU alquilados a través de [Marketplace de CLORE.AI](https://clore.ai/marketplace). {% endhint %} *** ## Requisitos del servidor | Parámetro | Mínimo | Recomendado | | --------- | ------------------------------- | -------------------------------------------- | | GPU | Cualquier GPU NVIDIA (opcional) | NVIDIA RTX 3080+ (para embeddings) | | VRAM | No es necesario para ChromaDB | 8–16 GB (para modelos locales de embeddings) | | RAM | 4 GB | 16–32 GB | | CPU | 2 núcleos | 8 núcleos | | Disco | 10 GB | 50–200 GB (para grandes conjuntos de datos) | | SO | Ubuntu 20.04+ | Ubuntu 22.04 | | Docker | Requerido | Docker + Docker Compose | | Puertos | 22, 8000 | 22, 8000 | {% hint style="info" %} ChromaDB en sí no requiere una GPU — funciona eficientemente en CPU. Sin embargo, **generar embeddings** (convertir texto en vectores) se beneficia enormemente de la aceleración por GPU. Si planeas usar modelos locales de embeddings (sentence-transformers, etc.), elige un servidor con GPU. {% endhint %} *** ## Despliegue rápido en CLORE.AI ### 1. Encuentra un servidor adecuado Ve a [Marketplace de CLORE.AI](https://clore.ai/marketplace) y elige: * **Solo CPU** para el servidor ChromaDB + API (almacenar embeddings precomputados) * **servidor GPU** si también quieres generar embeddings localmente ### 2. Configura tu despliegue **Imagen de Docker:** ``` chromadb/chroma:latest ``` **Mapeos de puertos:** ``` 22 → Acceso SSH 8000 → API HTTP de ChromaDB ``` **Variables de entorno:** ``` IS_PERSISTENT=TRUE ANONYMIZED_TELEMETRY=FALSE CHROMA_SERVER_AUTH_CREDENTIALS_FILE=/chroma/auth.txt ``` **Comando de inicio:** ```bash uvicorn chromadb.app:app --host 0.0.0.0 --port 8000 ``` ### 3. Probar el despliegue ```bash curl http://:8000/api/v1/heartbeat # Esperado: {"nanosecond heartbeat": } ``` *** ## Configuración paso a paso ### Paso 1: conéctate por SSH a tu servidor ```bash ssh root@ -p ``` ### Paso 2: Crear el directorio de datos ```bash mkdir -p /workspace/chromadb/data mkdir -p /workspace/chromadb/config ``` ### Paso 3: Ejecutar el contenedor 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 ``` ### Paso 4: Verificar que esté en ejecución ```bash # Comprobar el estado curl http://localhost:8000/api/v1/heartbeat # Comprobar versión curl http://localhost:8000/api/v1/version # Listar colecciones curl http://localhost:8000/api/v1/collections ``` ### Paso 5: Instalar el cliente de Python ```bash pip install chromadb pip install sentence-transformers # Para embeddings locales en GPU pip install openai # Para embeddings de OpenAI ``` ### Paso 6: Probar la conectividad desde Python ```python import chromadb client = chromadb.HttpClient(host="", port=8000) print(f"Versión de ChromaDB: {client.get_version()}") print(f"Heartbeat: {client.heartbeat()}") ``` ### Paso 7: (Opcional) Habilitar autenticación ```bash # Crear credenciales de autenticación echo "admin:$2y$12$$(openssl rand -hex 16)" > /workspace/chromadb/auth.txt # Ejecutar con autenticación habilitada 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 ``` *** ## Ejemplos de uso ### Ejemplo 1: Operaciones básicas del almacén vectorial ```python import chromadb from chromadb.utils import embedding_functions # Conectarse a ChromaDB en el servidor de Clore.ai client = chromadb.HttpClient( host="", port=8000 ) # Usar sentence-transformers para embeddings (se ejecuta en GPU si está disponible) embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction( model_name="all-MiniLM-L6-v2" ) # Crear una colección collection = client.get_or_create_collection( name="clore_ai_docs", embedding_function=embedding_fn, metadata={"hnsw:space": "cosine"} # Métrica de distancia ) # Añadir documentos documents = [ "Clore.ai es un mercado descentralizado de nube GPU para cargas de trabajo de IA.", "Puedes alquilar GPUs NVIDIA RTX 4090, A100 y H100 en Clore.ai.", "Clore.ai admite despliegues basados en Docker para cualquier framework de IA.", "Los precios en Clore.ai son competitivos en comparación con AWS y GCP.", "El marketplace de Clore.ai tiene miles de servidores GPU en todo el mundo.", "Puedes desplegar PyTorch, TensorFlow, JAX y otros frameworks de ML.", "Clore.ai ofrece precios spot para una computación GPU rentable.", ] 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"Se añadieron {len(documents)} documentos a la colección") print(f"Tamaño de la colección: {collection.count()} documentos") ``` *** ### Ejemplo 2: Búsqueda semántica ```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 ) # Consultas de búsqueda semántica queries = [ "¿Cuánto cuesta alquilar una GPU?", "¿Qué herramientas de aprendizaje automático están disponibles?", "Cuéntame sobre las opciones de hardware GPU", ] for query in queries: results = collection.query( query_texts=[query], n_results=3, include=["documents", "distances", "metadatas"] ) print(f"\n🔍 Consulta: {query}") for i, (doc, dist) in enumerate(zip( results["documents"][0], results["distances"][0] )): similarity = 1 - dist # Convertir distancia en similitud print(f" {i+1}. [{similarity:.3f}] {doc[:100]}...") ``` *** ### Ejemplo 3: Canal RAG con ChromaDB + OpenAI ```python import chromadb from chromadb.utils import embedding_functions from openai import OpenAI # Inicializar clientes chroma_client = chromadb.HttpClient(host="", port=8000) openai_client = OpenAI(api_key="your-openai-api-key") # Usar embeddings de OpenAI openai_ef = embedding_functions.OpenAIEmbeddingFunction( api_key="your-openai-api-key", model_name="text-embedding-3-small" ) # Obtener colección collection = chroma_client.get_or_create_collection( name="knowledge_base", embedding_function=openai_ef ) def add_to_knowledge_base(texts, ids=None, metadatas=None): """Añadir documentos a la base de conocimiento de 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"✓ Añadidos {len(texts)} documentos. Total: {collection.count()}") def rag_query(question, n_context=5): """Recuperar el contexto relevante y generar una respuesta con GPT-4.""" # 1. Recuperar documentos relevantes results = collection.query( query_texts=[question], n_results=n_context, include=["documents", "distances"] ) context_docs = results["documents"][0] distances = results["distances"][0] # 2. Construir cadena de contexto context = "\n\n".join([ f"[Fuente {i+1} (relevancia: {1-d:.2f})]: {doc}" for i, (doc, d) in enumerate(zip(context_docs, distances)) ]) # 3. Generar respuesta con LLM messages = [ { "role": "system", "content": "Eres un asistente útil. Responde a las preguntas basándote en el contexto proporcionado. Si la respuesta no está en el contexto, dilo." }, { "role": "user", "content": f"Contexto:\n{context}\n\nPregunta: {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] } # Ejemplo de uso knowledge = [ "Clore.ai es un marketplace de nube GPU con más de 45.000 usuarios.", "Clore.ai admite el despliegue de cargas de trabajo basadas en Docker.", "Los servidores GPU en Clore.ai van desde GTX 1080 hasta H100.", "Puedes desplegar aplicaciones de IA con acceso SSH y puertos personalizados.", ] add_to_knowledge_base(knowledge) result = rag_query("¿Cuántos usuarios tiene Clore.ai?") print(f"P: {result['question']}") print(f"R: {result['answer']}") ``` *** ### Ejemplo 4: Gestión de documentos con múltiples colecciones ```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" # Embeddings de mayor calidad ) # Crear colecciones separadas para distintos tipos de documentos 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), } # Añadir documentos a sus respectivas colecciones collections["technical_docs"].add( documents=["Guía de despliegue con Docker para Clore.ai", "Configuración SSH para servidores GPU"], ids=["tech_001", "tech_002"], metadatas=[{"type": "guide", "version": "v2"}, {"type": "config"}] ) collections["faq"].add( documents=["P: ¿Cómo pago? R: Mediante criptomoneda.", "P: ¿Qué GPUs? R: De RTX a H100."], ids=["faq_001", "faq_002"], metadatas=[{"category": "payment"}, {"category": "hardware"}] ) # Buscar en todas las colecciones 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 }) # Ordenar por relevancia all_results.sort(key=lambda x: x["similarity"], reverse=True) return all_results[:n_results * 2] results = search_all_collections("¿Cómo despliego con Docker?") for r in results: print(f"[{r['collection']}] ({r['similarity']:.3f}) {r['document'][:80]}...") ``` *** ### Ejemplo 5: Filtrado y consultas de metadatos ```python import chromadb client = chromadb.HttpClient(host="", port=8000) collection = client.get_collection("technical_docs") # Añadir documentos con metadatos enriquecidos collection.add( documents=[ "Guía: Ejecutar PyTorch en clusters de GPU NVIDIA A100", "Guía: entrenamiento distribuido de TensorFlow en RTX 4090", "Tutorial: ajuste fino de LLM con LoRA en GPU", "Referencia: matriz de compatibilidad de CUDA 12.1", "Guía: red de Docker para configuraciones multi-GPU", ], ids=["d1", "d2", "d3", "d4", "d5"], metadatas=[ {"type": "guide", "gpu": "A100", "framework": "pytorch", "year": 2024}, {"type": "guide", "gpu": "RTX4090", "framework": "tensorflow", "year": 2024}, {"type": "tutorial", "gpu": "any", "framework": "transformers", "year": 2024}, {"type": "reference", "gpu": "any", "framework": "cuda", "year": 2023}, {"type": "guide", "gpu": "multi", "framework": "docker", "year": 2024}, ] ) # Consultar con filtro de metadatos results = collection.query( query_texts=["Guía de entrenamiento con GPU"], n_results=3, where={"type": "guide"}, # Solo devolver guías include=["documents", "metadatas", "distances"] ) print("Resultados filtrados (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" Metadatos: {meta}") ``` *** ## Configuración ### Docker Compose (Producción) ```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 GB de caché 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 ``` ### Referencia de variables de entorno | Variable | Valor predeterminado | Descripción | | ----------------------------- | -------------------- | ---------------------------------------------------- | | `IS_PERSISTENT` | `FALSE` | Habilitar almacenamiento persistente | | `ANONYMIZED_TELEMETRY` | `TRUE` | Deshabilitar seguimiento de uso | | `CHROMA_SERVER_LOG_LEVEL` | `INFO` | Nivel de verbosidad del registro | | `CHROMA_MEMORY_LIMIT_BYTES` | Ninguno | Máximo de memoria para la caché de segmentos | | `ALLOW_RESET` | `FALSE` | Permitir restablecer todos los datos mediante la API | | `CHROMA_SERVER_AUTH_PROVIDER` | Ninguno | Clase del proveedor de autenticación | *** ## Consejos de rendimiento ### 1. Elegir el modelo de embeddings adecuado | Modelo | Dimensiones | Velocidad | Calidad | Se requiere GPU | | ------------------------ | ----------- | --------- | --------- | --------------- | | `all-MiniLM-L6-v2` | 384 | Rápido | Bueno | No | | `all-mpnet-base-v2` | 768 | Medio | Mejor | Opcional | | `text-embedding-3-small` | 1536 | Rápido | Excelente | Solo API | | `BAAI/bge-large-en-v1.5` | 1024 | Medio | Mejor | Sí | ### 2. Upserts por lotes para mayor velocidad ```python # Añadir en lotes de 100-1000 para el mejor rendimiento 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"Lote {i//BATCH_SIZE + 1} completado") ``` ### 3. Ajuste del índice HNSW ```python collection = client.create_collection( name="optimized", metadata={ "hnsw:space": "cosine", "hnsw:construction_ef": 200, # Mayor = mejor calidad del índice (construcción más lenta) "hnsw:search_ef": 100, # Mayor = mejor recuperación (búsqueda más lenta) "hnsw:M": 32, # Mayor = mejor recuperación (más memoria) } ) ``` ### 4. Cliente persistente para uso local ```python # Para desarrollo directamente en el servidor de Clore.ai import chromadb client = chromadb.PersistentClient(path="/workspace/chromadb/data") # No se necesita servidor, más rápido para uso en un solo proceso ``` *** ## Solución de problemas ### Problema: No se puede conectar a ChromaDB ```bash # Comprobar que el contenedor esté en ejecución docker ps | grep chromadb # Ver registros docker logs chromadb --tail 20 # Probar desde dentro del contenedor docker exec chromadb curl http://localhost:8000/api/v1/heartbeat ``` ### Problema: Se pierden los datos al reiniciar el contenedor ```bash # Asegurarse de que el volumen esté montado docker inspect chromadb | grep Mounts -A 10 # Volver a ejecutar con volumen explícito docker run -d -p 8000:8000 \\ -v /workspace/chromadb/data:/chroma/chroma \\ -e IS_PERSISTENT=TRUE \\ chromadb/chroma:latest ``` ### Problema: Errores de falta de memoria ```bash # Limitar la caché de memoria docker run -d -p 8000:8000 \\ -e CHROMA_MEMORY_LIMIT_BYTES=1073741824 \\ -v /workspace/chromadb/data:/chroma/chroma \\ chromadb/chroma:latest ``` ### Problema: Generación de embeddings lenta ```bash # Verificar que se esté usando la GPU para los embeddings python3 -c " import torch from sentence_transformers import SentenceTransformer model = SentenceTransformer('all-MiniLM-L6-v2', device='cuda') print(f'Embedding model on: {model.device}') " ``` ### Problema: No se encontró la colección después del reinicio ```bash # Verifica que la persistencia esté habilitada curl http://localhost:8000/api/v1/collections # Si está vacío, IS_PERSISTENT no se estableció o el volumen no se montó ``` *** ## Enlaces * **GitHub**: * **Documentación oficial**: * **Docker Hub**: * **PyPI**: * **Discord**: * **Marketplace de CLORE.AI**: *** ## Recomendaciones de GPU para Clore.ai | Caso de uso | GPU recomendada | Costo estimado en Clore.ai | | ------------------------------ | --------------- | -------------------------- | | Desarrollo/Pruebas | RTX 3090 (24GB) | $0.07–0.21/gpu/hr | | RAG de producción | RTX 3090 (24GB) | $0.07–0.21/gpu/hr | | Embeddings de alto rendimiento | RTX 4090 (24GB) | $0.14–0.42/gpu/hr | > 💡 Todos los ejemplos de esta guía pueden desplegarse en [Clore.ai](https://clore.ai/marketplace) servidores GPU. Explora las GPUs disponibles y alquila por hora: sin compromisos, acceso root completo. --- # 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-es/rag-y-bases-de-datos-vectoriales/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.