Intégrer Chroma local pour la recherche sémantique

Instructions

Détermine ces éléments avant d'écrire du code. Préfère les découvrir dans le repo et la demande de l'utilisateur. Pose des questions seulement si le choix change matériellement l'implémentation.

Forme du runtime
- Se connectent-ils à un serveur local en cours d'exécution, intègrent-ils Chroma dans les tests, ou mettent-ils en place un développement local à partir de zéro ?
- Décide s'ils ont besoin de chroma run, d'une commande Docker ou service, de HttpClient ou ChromaClient, ou de EphemeralClient Python.
Persistance
- Données locales persistantes : choisir un chemin de données intentionnel.
- Données de test jetables : utiliser les valeurs par défaut ou un répertoire temporaire.
Modèle d'embedding
- Réutiliser le fournisseur d'embedding existant de l'app si possible.
- Sinon, utiliser par défaut @chroma-core/default-embed en TypeScript ou l'équivalent local standard en Python.
- Si l'utilisateur veut explicitement les embeddings OpenAI en TypeScript, installer et utiliser @chroma-core/openai.
Forme des données indexées
- Déterminer ce qui est indexé, comment il doit être chunké, et quelles métadonnées sont nécessaires pour les filtres et les mises à jour.

Routing

Serveur local existant
- Confirmer l'hôte et le port avant de modifier le code client.
- Valider que le serveur est accessible avant de supposer que les collections manquent.
Développement local neuf
- Ajouter un chemin de démarrage local comme chroma run ou la commande Docker ou service existante du repo.
- Utiliser par défaut localhost:8000 sauf si le repo utilise déjà une autre adresse.
Tests Python ou workflows locaux jetables
- Préférer EphemeralClient quand la persistance n'est pas nécessaire.
- Signaler que les données sont perdues quand le processus se termine.
Développement local persistant
- Utiliser un chemin de données stable et rendre la persistance explicite dans le code ou la config.
- Ne pas basculer silencieusement entre les modes éphémère et persistant.
Travail d'intégration de recherche
- Utiliser getOrCreateCollection() en TypeScript ou get_or_create_collection() en Python.
- Concevoir les IDs de document et les métadonnées pour que les upserts et les suppressions soient simples.
- Grouper les écritures lors de la synchronisation de gros volumes de données.

Demander ou procéder

Demander d'abord :

Choix du modèle d'embedding (implications de coût et qualité)
S'ils ont besoin de données locales persistantes
Comment ils démarrent le serveur local
Stratégie d'isolation des données multi-tenant

Procéder avec des valeurs par défaut sensées :

Utiliser getOrCreateCollection() (TypeScript) / get_or_create_collection() (Python)
Utiliser la similarité cosinus (la plus commune)
Taille de chunk inférieure à 8 KB
Stocker les IDs source dans les métadonnées pour les mises à jour/suppressions
Utiliser un serveur local sur localhost:8000 sauf si le repo configure déjà une autre adresse ou utilise EphemeralClient Python

Ce qu'il faut valider

Import correct du client (ChromaClient, HttpClient, ou Client)
Package de fonction d'embedding installé (TypeScript)
Serveur local accessible avant de supposer que les collections manquent
Chemin local et mode de persistance intentionnels

Notes d'implémentation

Le Chroma local est le bon défaut pour le développement, les tests et les déploiements auto-hébergés.
Le Chroma OSS n'inclut pas les fonctionnalités exclusives à Chroma Cloud comme Schema() et Search().
Si l'utilisateur demande une récupération hybride dense et sparse, traiter cela comme une exigence probable de Chroma Cloud sauf si le repo implémente déjà une solution de contournement OSS.
Pour le Chroma open source, la récupération dense avec une seule fonction d'embedding est la baseline normale.

Motifs minimaux

Démarrer un serveur Chroma local quand le repo en a besoin :

chroma run

Adresse par défaut : localhost:8000.

Client local TypeScript :

import { ChromaClient } from 'chromadb';
import { DefaultEmbeddingFunction } from '@chroma-core/default-embed';

const client = new ChromaClient();

const embeddingFunction = new DefaultEmbeddingFunction();
const collection = await client.getOrCreateCollection({
  name: 'my_collection',
  embeddingFunction,
});

// Add documents
await collection.add({
  ids: ['doc1', 'doc2'],
  documents: ['First document text', 'Second document text'],
});

// Query
const results = await collection.query({
  queryTexts: ['search query'],
  nResults: 5,
});

Client local Python :

import chromadb

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

collection = client.get_or_create_collection(name="my_collection")

# Add documents
collection.add(
    ids=["doc1", "doc2"]   ,
    documents=["First document text", "Second document text"],
)

# Query
results = collection.query(
    query_texts=["search query"],
    n_results=5,
)

En savoir plus

Consulter le fichier llms.txt de Chroma seulement quand tu as besoin de détails API ou produit qui ne sont pas déjà dans le repo ou cette skill : https://docs.trychroma.com/llms.txt

Sujets disponibles

Typescript

Chroma Regex Filtering - Apprendre à utiliser les filtres regex dans les requêtes Chroma
Query and Get - Interroger et récupérer des données des collections Chroma
Metadata - Stocker et interroger les métadonnées, incluant les filtres et valeurs de tableau
Updating and Deleting - Mettre à jour les documents existants et supprimer les données des collections
Error Handling - Gérer les erreurs et défaillances en travaillant avec Chroma
Local Chroma - Comment exécuter et utiliser le chroma local

Python

Chroma Regex Filtering - Apprendre à utiliser les filtres regex dans les requêtes Chroma
Query and Get - Interroger et récupérer des données des collections Chroma
Metadata - Stocker et interroger les métadonnées, incluant les filtres et valeurs de tableau
Updating and Deleting - Mettre à jour les documents existants et supprimer les données des collections
Error Handling - Gérer les erreurs et défaillances en travaillant avec Chroma
Local Chroma - Comment exécuter et utiliser le chroma local

Général

Data Model - Aperçu de la façon dont Chroma stocke les données
Integrating Chroma into an existing system - Orientation pour ajouter la recherche Chroma à une application existante
Chroma CLI - Démarrer et gérer un serveur Chroma open source local via la CLI

chroma-local