Chroma 快速入门：Python 与 JavaScript 双栈指南

1. Chroma 简介与定位

Chroma 是一款面向 AI 应用的开源向量数据库（vector database），在 RAG（Retrieval-Augmented Generation）、知识库与语义搜索等场景中，通常承担文档存储与语义检索的核心角色。

它同时提供 Python 与 JavaScript/Node.js 两种官方客户端，开发者可以按技术栈选择安装方式：

Python：pip install chromadb
JavaScript/Node.js：npm install chromadb

接下来，我们将从安装部署开始，逐步介绍其核心 API 与进阶能力。

2. 安装与本地部署

Chroma 的安装非常轻量：

# Python 客户端
pip install chromadb

# JavaScript/Node.js 客户端
npm install chromadb

# 启动持久化的 client-server 服务
chroma run --path /chroma_db_path

默认情况下，Python 客户端 chromadb.Client() 以内存模式（in-memory）运行，适合快速原型开发。若需要数据持久化或对外提供服务，可切换到 client-server 模式，并通过 --path 指定持久化路径。JavaScript 客户端则采用 client-server 架构，需连接到一个运行中的 Chroma 服务。

生产环境的多节点部署、高可用、权限控制等运维细节，建议参考官方文档。

3. 核心 API 与使用流程

完成部署后，即可通过 Chroma 的核心 API 进行操作。常用的入口方法只有四个：create_collection、add、query 与 get。

Python 示例

import chromadb

# 默认内存模式，便于快速原型
client = chromadb.Client()

# 创建 collection；也支持 get_collection / get_or_create_collection / delete_collection
collection = client.create_collection("all-my-documents")

# 写入文档
collection.add(
    documents=["This is document1", "This is document2"],
    metadatas=[{"source": "notion"}, {"source": "google-docs"}],
    ids=["doc1", "doc2"],
)

# 语义检索
results = collection.query(
    query_texts=["This is a query document"],
    n_results=2,
)

JavaScript 示例

JavaScript 客户端的调用方式与 Python 类似，区别在于它通过 HTTP 与服务端交互：

import { ChromaClient } from "chromadb";

const client = new ChromaClient();
const collection = await client.getOrCreateCollection({ name: "all-my-documents" });

await collection.add({
  ids: ["doc1", "doc2"],
  documents: ["This is document1", "This is document2"],
  metadatas: [{ source: "notion" }, { source: "google-docs" }],
});

const results = await collection.query({
  queryTexts: ["This is a query document"],
  nResults: 2,
});

collection 是 Chroma 中组织数据的基本单元，支持创建、获取、删除等管理操作。

4. 数据写入与检索能力

在写入侧，collection.add() 会自动完成 embedding 与 indexing。如果不指定 embedding function，Chroma 会使用默认的 embedding 函数将文档转换为向量；当然，也可以传入自定义 embeddings 以满足更灵活的需求。

在检索侧，collection.query() 支持基于文本的相似度检索，并可通过以下方式过滤：

where：按 metadata 字段过滤
where_document：按文档内容过滤（例如 $contains）

results = collection.query(
    query_texts=["This is a query document"],
    n_results=2,
    where={"source": "notion"},
    where_document={"$contains": "query"}
)

5. Chroma Cloud 与扩展能力

除了本地与自托管部署，Chroma 还提供托管服务 Chroma Cloud，支持 serverless 向量搜索、混合搜索（hybrid search）与全文搜索（full-text search）。官方强调其在速度、成本、可扩展性和易用性方面的优势，新用户可以快速创建数据库并获得免费额度。

由于 Chroma 客户端天然采用 client-server 架构，从本地原型迁移到 Chroma Cloud 或自托管生产环境时，通常只需修改服务端点配置即可。

6. 开源生态与贡献

Chroma 采用 Apache 2.0 许可证，社区活跃，开发者可以通过以下方式参与：

加入 Discord 的 #contributing 频道
在 GitHub Issues 中认领 good first issue
阅读 Contributing Guide

Release Cadence：pypi 与 npm 包目前每周一发布新版本，hotfix 会随时发布。

原文来源：chroma-core/chroma README

原文链接

https://github.com/chroma-core/chroma

Chroma 快速入门与双栈实战指南