Chroma向量数据库使用指南：从入门到实践

Chroma向量数据库使用指南：从入门到实践

chroma the AI-native open-source embedding database 项目地址: https://gitcode.com/gh_mirrors/chrom/chroma

概述

Chroma是一个开源的向量数据库，专为存储和检索向量嵌入而设计。它提供了简单易用的API，支持多种编程语言，包括Python和JavaScript。本文将详细介绍Chroma的核心功能和使用方法，帮助开发者快速上手。

安装与初始化

Python环境安装

pip install chromadb

初始化持久化客户端

Chroma支持将数据持久化到本地磁盘，数据会自动保存并在下次启动时加载：

import chromadb
client = chromadb.PersistentClient(path="/path/to/save/to")

其中path参数指定数据库文件的存储位置。

客户端实用方法

# 心跳检测，确认客户端连接状态
client.heartbeat()  

# 重置数据库（⚠️不可逆操作）
client.reset()  

客户端-服务器模式

启动服务器

chroma run --path /db_path

连接服务器

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

异步客户端

import asyncio
import chromadb

async def main():
    client = await chromadb.AsyncHttpClient()
    collection = await client.create_collection(name="my_collection")
    await collection.add(documents=["hello world"], ids=["id1"])

asyncio.run(main())

集合(Collection)操作

创建集合

collection = client.create_collection(
    name="my_collection",
    embedding_function=emb_fn  # 可选嵌入函数
)

命名规范

• 长度3-63字符
• 以字母或数字开头结尾
• 可包含点、短横线和下划线
• 不能是有效的IP地址

集合管理

# 获取现有集合
collection = client.get_collection(name="test")  

# 获取或创建集合
collection = client.get_or_create_collection(name="test")  

# 删除集合（⚠️不可逆）
client.delete_collection(name="my_collection")  

实用方法

collection.peek()  # 查看前10项
collection.count()  # 统计项数
collection.modify(name="new_name")  # 重命名

距离函数配置

创建集合时可指定距离计算方法：

collection = client.create_collection(
    name="collection_name",
    metadata={"hnsw:space": "cosine"}  # 可选: l2(默认), ip, cosine
)

距离函数对比

| 方法 | 参数 | 公式 | 适用场景 | |------|------|------|----------| | 平方L2距离 | l2 | ∑(A_i-B_i)² | 一般向量比较 | | 内积 | ip | 1.0 - ∑(A_i×B_i) | 相似度计算 | | 余弦相似度 | cosine | 1.0 - ∑(A_i×B_i)/√(∑A_i²)×√(∑B_i²) | 文本相似度 |

数据操作

添加数据

collection.add(
    documents=["doc1", "doc2"],  # 原始文本
    embeddings=[[1.1, 2.3], [4.5, 6.9]],  # 可选预计算嵌入
    metadatas=[{"key": "value"}, ...],  # 元数据
    ids=["id1", "id2"]  # 唯一标识
)

查询数据

# 使用嵌入查询
results = collection.query(
    query_embeddings=[[11.1, 12.1], ...],
    n_results=10,
    where={"field": "value"},  # 元数据过滤
    where_document={"$contains":"text"}  # 文档内容过滤
)

# 使用文本查询(自动嵌入)
results = collection.query(
    query_texts=["query text", ...],
    n_results=10
)

按ID获取数据

items = collection.get(
    ids=["id1", "id2"],
    where={"field": "value"}
)

最佳实践

1. 嵌入维度一致性：确保添加的嵌入维度与集合创建时的维度一致
2. ID唯一性：每个文档必须有唯一ID，重复添加会覆盖原有数据
3. 元数据过滤：合理设计元数据结构，便于后续查询过滤
4. 距离函数选择：根据应用场景选择最适合的距离计算方法

通过本文介绍，开发者可以快速掌握Chroma的核心功能，在实际项目中实现高效的向量存储和检索。

chroma the AI-native open-source embedding database 项目地址: https://gitcode.com/gh_mirrors/chrom/chroma