Chroma
Chroma is a AI-native open-source vector database focused on developer productivity and happiness. Chroma is licensed under Apache 2.0.
This guide provides a quick overview for getting started with Chroma
vector stores
. For detailed
documentation of all Chroma
features and configurations head to the
API
reference.
Overview
Integration details
Class | Package | PY support | Package latest |
---|---|---|---|
Chroma | @langchain/community | ✅ |
Setup
To use Chroma vector stores, you’ll need to install the
@langchain/community
integration package along with the Chroma JS
SDK as a peer dependency.
This guide will also use OpenAI
embeddings, which require you
to install the @langchain/openai
integration package. You can also use
other supported embeddings models
if you wish.
- npm
- yarn
- pnpm
npm i @langchain/community @langchain/openai chromadb
yarn add @langchain/community @langchain/openai chromadb
pnpm add @langchain/community @langchain/openai chromadb
Next, follow the following instructions to run Chroma with Docker on your computer:
docker pull chromadb/chroma
docker run -p 8000:8000 chromadb/chroma
You can see alternative setup instructions in this guide.
Credentials
If you are running Chroma through Docker, you do not need to provide any credentials.
If you are using OpenAI embeddings for this guide, you’ll need to set your OpenAI key as well:
process.env.OPENAI_API_KEY = "YOUR_API_KEY";
If you want to get automated tracing of your model calls you can also set your LangSmith API key by uncommenting below:
// process.env.LANGCHAIN_TRACING_V2="true"
// process.env.LANGCHAIN_API_KEY="your-api-key"
Instantiation
import { Chroma } from "@langchain/community/vectorstores/chroma";
import { OpenAIEmbeddings } from "@langchain/openai";
const embeddings = new OpenAIEmbeddings({
model: "text-embedding-3-small",
});
const vectorStore = new Chroma(embeddings, {
collectionName: "a-test-collection",
url: "http://localhost:8000", // Optional, will default to this value
collectionMetadata: {
"hnsw:space": "cosine",
}, // Optional, can be used to specify the distance method of the embedding space https://docs.trychroma.com/usage-guide#changing-the-distance-function
});
Manage vector store
Add items to vector store
import type { Document } from "@langchain/core/documents";
const document1: Document = {
pageContent: "The powerhouse of the cell is the mitochondria",
metadata: { source: "https://example.com" },
};
const document2: Document = {
pageContent: "Buildings are made out of brick",
metadata: { source: "https://example.com" },
};
const document3: Document = {
pageContent: "Mitochondria are made out of lipids",
metadata: { source: "https://example.com" },
};
const document4: Document = {
pageContent: "The 2024 Olympics are in Paris",
metadata: { source: "https://example.com" },
};
const documents = [document1, document2, document3, document4];
await vectorStore.addDocuments(documents, { ids: ["1", "2", "3", "4"] });
[ '1', '2', '3', '4' ]
Delete items from vector store
You can delete documents from Chroma by id as follows:
await vectorStore.delete({ ids: ["4"] });
Query vector store
Once your vector store has been created and the relevant documents have been added you will most likely wish to query it during the running of your chain or agent.
Query directly
Performing a simple similarity search can be done as follows:
const filter = { source: "https://example.com" };
const similaritySearchResults = await vectorStore.similaritySearch(
"biology",
2,
filter
);
for (const doc of similaritySearchResults) {
console.log(`* ${doc.pageContent} [${JSON.stringify(doc.metadata, null)}]`);
}
* The powerhouse of the cell is the mitochondria [{"source":"https://example.com"}]
* Mitochondria are made out of lipids [{"source":"https://example.com"}]
See this page for more on Chroma filter syntax.
If you want to execute a similarity search and receive the corresponding scores you can run:
const similaritySearchWithScoreResults =
await vectorStore.similaritySearchWithScore("biology", 2, filter);
for (const [doc, score] of similaritySearchWithScoreResults) {
console.log(
`* [SIM=${score.toFixed(3)}] ${doc.pageContent} [${JSON.stringify(
doc.metadata
)}]`
);
}
* [SIM=0.835] The powerhouse of the cell is the mitochondria [{"source":"https://example.com"}]
* [SIM=0.852] Mitochondria are made out of lipids [{"source":"https://example.com"}]
Query by turning into retriever
You can also transform the vector store into a retriever for easier usage in your chains.
const retriever = vectorStore.asRetriever({
// Optional filter
filter: filter,
k: 2,
});
await retriever.invoke("biology");
[
Document {
pageContent: 'The powerhouse of the cell is the mitochondria',
metadata: { source: 'https://example.com' },
id: undefined
},
Document {
pageContent: 'Mitochondria are made out of lipids',
metadata: { source: 'https://example.com' },
id: undefined
}
]
Usage for retrieval-augmented generation
For guides on how to use this vector store for retrieval-augmented generation (RAG), see the following sections:
- Tutorials: working with external knowledge.
- How-to: Question and answer with RAG
- Retrieval conceptual docs
API reference
For detailed documentation of all Chroma
features and configurations
head to the API
reference
Related
- Vector store conceptual guide
- Vector store how-to guides