Chroma-core项目开发环境搭建与使用指南

Chroma-core项目开发环境搭建与使用指南

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

项目概述

Chroma-core是一个用于构建AI应用程序的向量数据库，它提供了高效的向量存储和检索功能。本文将详细介绍如何搭建Chroma-core的开发环境，以及如何在本地运行和测试该项目。

开发环境准备

虚拟环境配置

在开始开发前，强烈建议创建一个独立的Python虚拟环境：

python3 -m venv venv      # 创建虚拟环境
source venv/bin/activate  # 激活虚拟环境

依赖安装

激活虚拟环境后，安装项目依赖：

pip install -r requirements.txt      # 安装运行依赖
pip install -r requirements_dev.txt  # 安装开发依赖
pre-commit install                   # 安装git预提交钩子

对于MacOS用户，还需要安装protobuf：

brew install protobuf

本地安装

为了便于开发，可以以可编辑模式安装chromadb：

pip install -e .

运行Chroma数据库

Chroma支持三种运行模式，满足不同场景需求：

1. 独立内存模式

最简单的运行方式，数据仅保存在内存中：

import chromadb
api = chromadb.Client()
print(api.heartbeat())  # 检查服务状态

2. 持久化模式

数据会持久化到本地文件系统：

import chromadb
api = chromadb.PersistentClient(path="/path/to/persist/directory")
print(api.heartbeat())

3. 客户端-服务端模式

先启动服务端：

chroma run --path /chroma_db_path

然后使用客户端连接：

import chromadb
api = chromadb.HttpClient(host="localhost", port=8000)
print(api.heartbeat())

分布式开发环境搭建

对于需要开发分布式Chroma的场景，可以使用Tilt工具：

前提条件

• Docker环境
• 本地Kubernetes集群（Mac推荐OrbStack，Linux推荐Kind）
• Tilt工具
• Helm包管理器

启动分布式环境

tilt up

该命令会自动创建所有必要的Kubernetes资源并构建Docker镜像。完成后，Chroma服务将暴露在8000端口，Tilt仪表板可通过http://localhost:10350/访问。

停止服务使用：

tilt down

测试与构建

运行测试

项目测试位于/chromadb/test目录，运行全部测试：

pytest

手动构建

构建Rust代码和类型绑定：

maturin dev

构建项目分发包：

python -m build

构建产物会输出到dist目录。

版本管理机制

项目采用PyPA的setuptools_scm模块进行版本管理，版本号基于Git信息自动生成：

1. 如果当前Git HEAD有标签，版本号即为标签名（如0.0.1）
2. 如果无标签但代码干净，版本号为最近标签的补丁版本+devN（如0.0.2-dev5）
3. 如果代码有未提交更改，会追加+dirty（如0.0.2-dev5+dirty）

查看当前版本号：

python -m setuptools_scm

开发建议

1. 始终在虚拟环境中开发，避免污染系统Python环境
2. 提交代码前运行pre-commit检查
3. 修改Rust代码后记得运行maturin dev重新构建
4. 分布式开发时注意资源占用，及时清理测试环境

通过本文介绍的方法，开发者可以快速搭建Chroma-core的开发环境，并根据需求选择合适的运行模式进行开发和测试。

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