Notions fondamentales sur la base de données vectorielle Chroma et comment en provisionner une avec Stripe Projects

Projects

Ajoutez des services, générez des identifiants et gérez la facturation depuis la CLI, ou laissez votre agent s’en charger.

En savoir plus 
  1. Introduction
  2. Key takeaways
  3. What is Chroma?
  4. Why use Chroma for AI search?
  5. How do you configure a Chroma vector database manually?
    1. 1. Choose a deployment option
    2. 2. Install the client library
    3. 3. Create the database and generate credentials
    4. 4. Configure authentication and connection values
  6. How do you set up Chroma using Stripe Projects?
    1. 1. Install the plugin
    2. 2. Initialize a workspace
    3. 3. Browse the catalog
    4. 4. Provision Chroma
    5. 5. Join an existing project
    6. 6. Keep environments separate
    7. 7. Check status and stay in sync
  7. How do you integrate Chroma into your application?
    1. 1. Create a client and a collection
    2. 2. Add documents
    3. 3. Query by similarity
  8. What are the best practices and common pitfalls when using a Chroma vector database?
  9. How Stripe Projects can help

The vector database market is projected to grow to over $15 billion by 2034. Provisioning a Chroma vector database means you’ll need to pick a deployment option, install the client library, generate an application programming interface (API) key from a dashboard, and copy it into your application’s environment variables. If you do that manually, you’ll repeat many of those steps for each additional service your application depends on, from hosting to authentication.

Stripe Projects offers a shorter path: a single command-line interface (CLI) command provisions the Chroma database, encrypts the credentials, and writes them straight to your .env file, alongside whatever other providers your project already uses. Stripe Projects handles provisioning, credential storage, and billing for third-party infrastructure services.

Below, we discuss what Chroma actually is and why it fits artificial intelligence (AI) search, how manual setup works, and how Stripe Projects simplifies the process.

Key takeaways

  • Chroma is an open-source vector database that stores embeddings and returns results ranked by meaning instead of exact keyword matches.
  • To set up Chroma manually, you’ll create credentials in a separate dashboard for every provider your application uses, then keep them all in sync by hand.

  • Stripe Projects provisions Chroma and other third-party services with a single command-line interface (CLI) command and syncs the resulting credentials to your local environment automatically.

What is Chroma?

Chroma is an open-source database built for storing and searching embeddings, the numerical vectors that represent the meaning of text, images, or audio. While a traditional database matches exact values, Chroma finds items with similar meaning by comparing vectors in high-dimensional space.

Large language models (LLMs) can’t reason about information they’ve never seen, and their training data has a cutoff date. Chroma sits between your raw content and your AI model, narrowing millions of records down to those that matter for a given query.

Specifically, it serves three functions:

  • Retrieval-augmented generation: An application searches a knowledge base or document set for passages related to a user’s question, then passes those passages to a language model alongside the question itself.

  • Semantic search: A user searches a product catalog or support archive using natural language and receives results ranked by meaning rather than by matching keywords.

  • Recommendations: An application compares a user’s activity or a document’s embedding against a library of other items, and it surfaces those with the closest vectors.

How do you configure a Chroma vector database manually?

Setting up Chroma directly means choosing from a handful of options. None are difficult individually, but each adds a separate dashboard and credential to track. Here’s how it works:

1. Choose a deployment option

Run Chroma in-memory for local testing, use the persistent client to save data to disk on a single machine, run it in client-server mode so multiple applications can share the same instance, or use Chroma Cloud for a serverless, managed database.

2. Install the client library

Run pip install chromadb for a Python project, or install the equivalent npm package for a JavaScript or TypeScript project.

3. Create the database and generate credentials

If you’re using Chroma Cloud or a self-hosted server, sign up for an account, create a database instance, and generate an API key through a dashboard.

4. Configure authentication and connection values

Copy the API key, a database identifier or tenant ID, and a host URL into environment variables. Then instantiate a client such as CloudClient or HttpClient with those values.

This last step can get complicated when you copy credentials from one dashboard into a .env file, then repeat the process for additional services the application depends on, such as a hosting provider or an authentication service. Since each provider names its variables differently, rotates keys on its own schedule, and stores everything in a separate dashboard, a new teammate has to hunt down credentials from three or four different places before the project can run.

How do you set up Chroma using Stripe Projects?

Stripe Projects is a CLI plugin, currently in public preview, that provisions third-party database, hosting, and AI services from your terminal instead of using each provider’s separate dashboard. Here’s how you can use it to configure Chroma:

1. Install the plugin

Run stripe plugin install projects once, on top of the standard Stripe CLI.

2. Initialize a workspace

Run stripe projects init from your project directory to create a .projects directory with state files that track which services and resources the project uses, along with a .env file for local credentials; Stripe adds the credential files to .gitignore automatically.

3. Browse the catalog

Run stripe projects catalog to see all available providers, or stripe projects search vector to find Chroma and other vector databases by keyword.

4. Provision Chroma

Run stripe projects add chroma/database to associate a Chroma provider account with your Stripe account—you’ll need to register first if necessary. This command also provisions a database resource, encrypts the resulting credentials, and writes the connection values to your .env file.

5. Join an existing project

Run stripe projects pull <project-id> with the project ID from stripe projects list to connect to an existing Chroma resource and write a local copy of the credentials instead of provisioning a new one.

6. Keep environments separate

Create named environments for development and production with stripe projects env create <name> --output <path>, so each one syncs its Chroma credentials to a separate output file instead of sharing a single .env.

7. Check status and stay in sync

Run stripe projects status to see every provider linked to the project along with its plan tier and health, and stripe projects env --pull to re-sync your .env any time a credential rotates or a teammate changes the setup.

How do you integrate Chroma into your application?

Once your .env file has the right connection values, whether provided by Stripe Projects or entered manually, you’ll follow the same pattern to integrate Chroma:

1. Create a client and a collection

To instantiate a client such as chromadb.CloudClient(), pass in the API key, tenant, and database values from your environment variables (the same ones Stripe Projects writes to .env when you provision Chroma), then call client.get_or_create_collection(name="support_docs") to create the collection or reuse it if it already exists.

2. Add documents

Call collection.add() with a list of unique IDs, the raw documents such as Refunds process within 5 business days, and optional metadata such as {“category”: “refunds”}; Chroma generates the embeddings automatically using a default model, or you can supply your own if you’re working with a specific provider such as OpenAI or Cohere.

3. Query by similarity

Call collection.query() with a list of query_texts and an n_results value; Chroma embeds the query text, compares it against the stored vectors, and returns the closest documents ranked by distance. If you leave out n_results, Chroma returns 10 matches by default.

From there, your application typically passes the retrieved content into a language model’s context window as supporting material for a response. Whatever embedding model generated your stored vectors has to be the same one, with matching dimensions, that generates your query vectors. If you mix embedding models partway through a project, the search results will look wrong without ever throwing an error. This makes the bug difficult to detect until someone notices the retrieved passages don’t match the question.

What are the best practices and common pitfalls when using a Chroma vector database?

Many Chroma problems trace back to a few common decisions.

These are the main areas to get right:

  • Chunking strategy: Break long documents into smaller passages before embedding them. A single embedding for an entire document tends to blur the meaning of any one section within it, but chunks of a few hundred words retrieve more precisely.

  • Metadata filters: Attach metadata such as a source, date, or category to every document you add; filtering by metadata during a similarity search narrows results without relying on vector distance alone.

  • Embedding consistency: Keep a record of which embedding model and version indexed each collection; re-embed the whole collection if you switch models rather than mixing vectors from two different models.

  • Collection naming and reindexing: Name collections by content type or source rather than by date or version; rebuild it from scratch when your chunking strategy or embedding model changes materially.

  • Access controls: Treat your Chroma API key with the same caution as any other credential; don’t hardcode it into client-side code where end users could expose it.

Don’t store sensitive source content, such as personal data or internal documents, in a collection without proper access controls, and don’t trust vector similarity without testing retrieval quality against real questions. These are two mistakes that come up often.

How Stripe Projects can help

Stripe Projects lets developers and their AI agents add services, generate credentials, and manage billing from the command line interface (CLI).

Stripe Projects helps you:

  • Provision third-party services from the command line: Use one workflow to add services, manage credentials, and upgrade plans, instead of different tools and workflows for every provider. Manage hosting, databases, auth, AI, and more without needing dashboards, config files, or infrastructure code.

  • Sync credentials automatically: Keep environment variables portable across local setups, machines, teammates, and agents—no copy-pasting API keys.

  • Manage billing from the CLI or your coding agent: Set up billing details once and securely share them with third-party services. Upgrade and downgrade tiers, monitor usage, and manage subscriptions from the CLI.

Learn more about how Stripe Projects helps simplify app provisioning, or copy and paste this command into your terminal to get started today:

brew install stripe/stripe-cli/stripe && stripe plugin install projects && npx skills add https://github.com/stripe/ai --skill stripe-projects -y -g

Le contenu de cet article est fourni à des fins informatives et pédagogiques uniquement. Il ne saurait constituer un conseil juridique ou fiscal. Stripe ne garantit pas l'exactitude, l'exhaustivité, la pertinence, ni l'actualité des informations contenues dans cet article. Nous vous conseillons de solliciter l'avis d'un avocat compétent ou d'un comptable agréé dans le ou les territoires concernés pour obtenir des conseils adaptés à votre situation.

Plus d'articles

  • Un problème est survenu. Veuillez réessayer ou contacter le service de support.

Envie de vous lancer ?

Créez un compte et commencez à accepter des paiements rapidement, sans avoir à signer de contrat ni à fournir vos coordonnées bancaires. N'hésitez pas à nous contacter pour discuter de solutions personnalisées pour votre entreprise.
Payments

Payments

Acceptez des paiements en ligne, en personne et dans le monde entier, grâce à une solution de paiement adaptée à toutes les entreprises.

Documentation Payments

Trouvez un guide qui vous aidera à intégrer les API de paiement Stripe.