# chroma-study

**Repository Path**: learning-python_1/chroma-study

## Basic Information

- **Project Name**: chroma-study
- **Description**: Python的向量数据库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-18
- **Last Updated**: 2026-01-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ChromaDB 向量数据库学习笔记

## 目录
- [项目概述](#项目概述)
- [环境配置](#环境配置)
- [核心概念](#核心概念)
- [第一章：集合操作](#第一章集合操作)
- [第二章：集合的CRUD操作](#第二章集合的crud操作)
- [工具类说明](#工具类说明)
- [总结](#总结)

---

## 项目概述

本项目是一个关于 ChromaDB 向量数据库的学习练习项目。ChromaDB 是一个开源的向量数据库，用于存储和检索嵌入向量，常用于构建 RAG（检索增强生成）应用、语义搜索等场景。

### 项目结构
```
chroma-study/
├── ch01/              # 第一章：集合操作
│   └── collection_demo.py
├── ch02/              # 第二章：集合的CRUD操作
│   ├── add_demo.py    # 添加文档
│   ├── delete_demo.py # 删除文档
│   └── query_demo.py  # 查询文档
├── utils/             # 工具类
│   ├── chroma_utils.py    # ChromaDB工具函数
│   └── openai_utils.py    # OpenAI嵌入函数
├── requirements.txt   # 依赖包
└── README.md          # 项目说明
```

---

## 环境配置

### 依赖安装
主要依赖包：
- `chromadb==1.4.0` - ChromaDB向量数据库
- `openai==2.14.0` - OpenAI API客户端（用于生成嵌入向量）

安装命令：
```bash
pip install -r requirements.txt
```

### API配置
项目使用自定义的 OpenAI API 端点：
- API Base: `https://api.qingyuntop.top/v1`
- Model: `text-embedding-3-large`
- API Key: 在 `utils/chroma_utils.py` 和 `utils/openai_utils.py` 中配置

---

## 核心概念

### 1. Collection（集合）
- **定义**：集合是嵌入存储、文档和任何元数据的地方
- **作用**：类似于传统数据库中的表，用于组织和管理相关的文档和向量

### 2. Embedding（嵌入向量）
- **定义**：将文本转换为数值向量的过程
- **用途**：使计算机能够理解和比较文本的语义相似性
- **模型**：使用 `text-embedding-3-large` 模型生成向量

### 3. Metadata（元数据）
- **定义**：与文档关联的额外信息
- **用途**：用于过滤、分类和组织文档

### 4. 向量检索算法
- **cosine（余弦相似度）**：文本检索首选，衡量向量方向的相似性
- **l2（欧几里得距离）**：视觉模型首选，衡量向量间的距离
- **ip（内积）**：另一种相似度计算方法

---

## 第一章：集合操作

### 学习目标
掌握 ChromaDB 集合的创建、获取、删除和列表操作。

### 核心代码

#### 1. 获取或创建集合
```python
from utils.chroma_utils import get_or_create_collection

# 如果集合不存在则创建，存在则返回
collection = get_or_create_collection("test_c1")
```

#### 2. 创建客户端
```python
from utils.chroma_utils import chroma_client

client = chroma_client()
```

#### 3. 创建集合
```python
client.create_collection(name="test_c2")
```

#### 4. 获取集合
```python
c2 = client.get_collection(name="test_c2")
```

#### 5. 删除集合
```python
client.delete_collection(name="test_c2")
```

#### 6. 遍历所有集合
```python
collections = client.list_collections()
for coll in collections:
    print(coll)
```

### 知识点总结
- **客户端模式**：
  - 内存模式：`chromadb.Client()` - 数据仅存储在内存中
  - 持久化模式：`chromadb.PersistentClient(path="./chromadb")` - 数据持久化到磁盘
  - 远程访问模式：`chromadb.HttpClient(host="127.0.0.1", port=8000)` - 连接到远程服务器

---

## 第二章：集合的CRUD操作

### 2.1 添加文档（Add）

#### 方法一：只保存文档（自动生成嵌入向量）
```python
def add_document(docs: List[str], metadatas: List[Dict], ids: List[str]):
    """
    添加文档 - 只保存文档，ChromaDB会自动调用embedding_function生成向量
    """
    collection.add(
        documents=docs,      # 文档集合
        metadatas=metadatas, # 元数据
        ids=ids              # 文档ID
    )
```

#### 方法二：保存文档和自定义嵌入向量（推荐）
```python
def add_embedding(docs: List[str], metadatas: List[Dict], ids: List[str]):
    """
    保存文档和嵌入的向量
    """
    embedd_list = []
    for doc in docs:
        # 手动生成嵌入向量
        embedd_list.append(embedding(doc))
    
    collection.add(
        documents=docs,      # 保存文档
        embeddings=embedd_list,  # 保存嵌入的向量
        metadatas=metadatas, # 文档元数据
        ids=ids              # 文档ID
    )
```

#### 使用示例
```python
docs = ["珠海是一个海滨城市", "惠州是一座非常适合移居的城市"]
metadata = [{"city": "珠海"}, {"city": "惠州"}]
ids = ["c1", "c2"]

add_embedding(docs, metadata, ids)
```

### 2.2 删除文档（Delete）

#### 方法一：根据ID删除
```python
def delete(ids: List[str]):
    """
    根据id删除文档
    """
    collection.delete(ids)
    print("删除成功")
```

#### 方法二：根据元数据条件删除
```python
def delete_where(metadatas: Dict):
    """
    将元数据作为删除条件
    """
    collection.delete(where=metadatas)
    print("删除元数据成功")
```

#### 使用示例
```python
# 根据ID删除
ids = ["c1"]
delete(ids)

# 根据元数据删除
metadatas = {"city": "珠海"}
delete_where(metadatas)
```

### 2.3 查询文档（Query）

#### 方法一：根据ID获取文档
```python
def get_document(ids: List[int]):
    """
    根据id查找文档
    如果要显示向量集合，使用include参数包含embeddings字段
    """
    return collection.get(ids, include=["embeddings"])
```

#### 方法二：向量检索（语义搜索）
```python
def query(prompt: str):
    """
    内容检索 - 基于语义相似度的向量检索
    """
    return collection.query(
        query_texts=prompt,  # 查询文本（会自动转换为向量）
        n_results=1,         # 指定检索返回的条数
        # include=["embeddings"],  # 可选：包含向量数据
    )
```

#### 使用示例
```python
# 根据ID获取
result = get_document(["c1"])

# 语义搜索
result = query("珠海")
print(result)
```

### CRUD操作总结

| 操作 | 方法 | 说明 |
|------|------|------|
| **Create** | `collection.add()` | 添加文档和向量 |
| **Read** | `collection.get()` / `collection.query()` | 根据ID获取或语义搜索 |
| **Update** | 通过删除+添加实现 | ChromaDB不直接支持更新 |
| **Delete** | `collection.delete()` | 根据ID或元数据删除 |

---

## 工具类说明

### chroma_utils.py

#### 1. chroma_client()
创建 ChromaDB 客户端，支持三种模式：
- **内存模式**：数据不持久化
- **持久化模式**：数据保存到 `./chromadb` 目录
- **远程访问模式**：连接到远程 ChromaDB 服务器

#### 2. get_or_create_collection()
获取或创建集合，配置了：
- **嵌入函数**：使用 OpenAI 的 `text-embedding-3-large` 模型
- **检索算法**：使用余弦相似度（cosine）算法
- **API配置**：自定义的 OpenAI API 端点

### openai_utils.py

#### embedding()
将文本转换为嵌入向量：
- 使用 OpenAI API 生成向量
- 返回向量数组（list）

---

## 关键知识点

### 1. 向量数据库的优势
- **语义搜索**：能够理解文本的语义，而不仅仅是关键词匹配
- **相似度检索**：可以找到语义相似的内容
- **高效检索**：使用向量索引实现快速检索

### 2. 嵌入向量的生成
- 使用预训练的模型（如 OpenAI 的 embedding 模型）
- 将文本转换为固定维度的数值向量
- 语义相似的文本会产生相似的向量

### 3. 检索算法选择
- **cosine（余弦相似度）**：
  - 适合文本检索
  - 衡量向量方向的相似性
  - 范围：-1 到 1，值越大越相似
  
- **l2（欧几里得距离）**：
  - 适合视觉模型
  - 衡量向量间的实际距离
  - 值越小越相似

- **ip（内积）**：
  - 另一种相似度计算方法
  - 需要考虑向量归一化

### 4. 元数据的作用
- **过滤**：可以根据元数据过滤查询结果
- **分类**：用于文档分类和组织
- **删除**：可以根据元数据批量删除文档

---

## 实践建议

### 1. 数据准备
- 确保文档质量高，语义清晰
- 合理设计元数据结构，便于后续过滤和检索
- 为每个文档分配唯一的ID

### 2. 性能优化
- 批量添加文档时，考虑分批处理
- 合理设置 `n_results` 参数，避免返回过多结果
- 对于大量数据，考虑使用持久化模式

### 3. 错误处理
- 添加异常处理机制
- 检查集合是否存在
- 验证输入数据的格式

### 4. 应用场景
- **RAG系统**：检索增强生成
- **语义搜索**：智能文档搜索
- **推荐系统**：基于内容相似度的推荐
- **问答系统**：知识库检索

---

## 总结

### 学习收获
1. ✅ 掌握了 ChromaDB 的基本操作（集合的创建、删除、查询）
2. ✅ 理解了向量数据库的核心概念（集合、嵌入向量、元数据）
3. ✅ 学会了文档的添加、删除和查询操作
4. ✅ 了解了不同检索算法的适用场景
5. ✅ 掌握了使用 OpenAI API 生成嵌入向量的方法

### 下一步学习方向
- [ ] 学习更新文档的方法（删除+重新添加）
- [ ] 探索更复杂的查询条件（元数据过滤）
- [ ] 学习批量操作和性能优化
- [ ] 了解 ChromaDB 的高级特性（如集合的更新、备份等）
- [ ] 实践构建完整的 RAG 应用

### 参考资料
- [ChromaDB 官方文档](https://docs.trychroma.com/)
- [OpenAI Embeddings API](https://platform.openai.com/docs/guides/embeddings)

---

*笔记生成时间：2025年*
*项目路径：D:\System\Desktop\SPS\chroma-study*