向量数据库是 AI 时代的核心基础设施，专门用于存储、管理和检索 “向量数据”（文本、图像、音频等转化后的数值序列），核心优势是高效的相似性查询，广泛应用于语义搜索、推荐系统、AI 问答、图像检索等场景。

Chroma 是一款轻量级、开源、易用的向量数据库，无需复杂配置，纯 Python 即可上手，完美适配新手入门，同时支持生产环境部署，兼顾易用性与扩展性。本教程将由浅入深，从基础概念到实战案例，全程附可直接复制运行的代码，零基础也能轻松掌握。

本教程核心特点：纯 Python 实现、步骤清晰、示例完整、避坑指南，学会后可独立完成向量存储、相似性查询、AI 结合等实战需求。

---

一、基础认知：什么是向量数据库与 Chroma？

1. 核心概念（新手必看）

• 向量（Embedding）：将文本、图像等非结构化数据，通过模型（如 Sentence-BERT、OpenAI Embedding）转化为的一串数值（如 [0.123, 0.456, ...]），是计算机理解数据语义的核心格式。
• 向量数据库：专门存储向量数据，并提供高效相似性查询（如余弦相似度）的数据库，区别于传统关系型数据库（存储结构化数据），核心能力是 “找相似”。
• Chroma 核心优势：轻量无依赖（无需单独部署服务，可嵌入 Python 代码）、API 简洁、支持自动嵌入（无需手动转化向量）、支持持久化存储、兼容主流嵌入模型，新手友好度拉满。

2. Chroma 适用场景

1. 语义搜索：根据文本语义找相似内容（如 “推荐和机器学习相关的文章”）；
2. AI 问答（RAG）：将知识库存入 Chroma，结合 LLM 实现精准问答；
3. 相似内容推荐：如商品推荐、文章推荐、图片检索；
4. 数据去重：找到相似的文本、图像，实现去重处理。

---

二、环境准备（第一步必做，零基础友好）

1. 前提条件

确保电脑安装 Python 3.8 及以上版本（官网下载即可，安装时勾选 “Add Python to PATH”），无需提前安装其他数据库（Chroma 可本地运行）。

2. 安装 Chroma 库

打开命令提示符（CMD）/ 终端，执行以下命令（国内环境建议用镜像源，加快安装速度）：

# 国内镜像源（推荐，避免超时）
pip install chromadb -i https://pypi.tuna.tsinghua.edu.cn/simple
# 默认源（国外环境可用）
# pip install chromadb

3. 安装嵌入模型依赖（可选但推荐）

Chroma 默认自带轻量级嵌入模型（all-MiniLM-L6-v2），可直接使用；若需更精准的嵌入效果，可安装 Sentence-BERT（常用嵌入模型）：

pip install sentence-transformers -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 验证安装

执行以下代码，无报错即安装成功：

Python

import chromadb
# 初始化客户端（内存模式，仅测试）
client = chromadb.Client()
print("Chroma安装成功！")

✅ 运行后打印 “Chroma 安装成功！”，即可进入下一步学习。

---

三、快速入门：第一个 Chroma 实例（5 分钟上手）

本节将完成最基础的流程：初始化 Chroma 客户端 → 创建集合 → 添加数据（自动转化为向量） → 相似性查询，代码可直接复制运行。

1. 完整示例代码（新手直接复制）

Python

# 1. 导入Chroma库
import chromadb

# 2. 初始化Chroma客户端（内存模式：数据仅在当前程序运行时存在，关闭即丢失）
client = chromadb.Client()

# 3. 创建一个集合（Collection）：相当于数据库中的“表”，用于存储相关的向量数据
# name：集合名称（自定义，唯一），metadata：集合描述（可选）
collection = client.create_collection(name="my_first_collection", metadata={"description": "测试集合"})

# 4. 向集合中添加数据（自动转化为向量，无需手动处理）
# ids：每条数据的唯一标识（字符串类型，不可重复）
# documents：要存储的文本数据（可传入列表，批量添加）
# metadata：每条数据的附加信息（可选，如分类、时间等）
collection.add(
    ids=["1", "2", "3", "4"],
    documents=[
        "Python是一门简洁易用的编程语言，适合AI开发",
        "Chroma是一款轻量级向量数据库，支持Python API",
        "向量数据库用于存储和检索嵌入向量，核心是相似性查询",
        "Sentence-BERT是常用的文本嵌入模型，可将文本转化为向量"
    ],
    metadatas=[
        {"category": "编程语言"},
        {"category": "向量数据库"},
        {"category": "概念解释"},
        {"category": "嵌入模型"}
    ]
)

# 5. 相似性查询（核心功能）：根据查询文本，找到最相似的3条数据
# query_texts：查询文本（可传入列表，批量查询）
# n_results：返回的相似结果数量
results = collection.query(
    query_texts=["什么是向量数据库？"],  # 查询文本
    n_results=3  # 返回前3条最相似的数据
)

# 6. 打印查询结果（解读结果格式）
print("查询结果：")
print("相似文档：", results["documents"])
print("文档ID：", results["ids"])
print("相似度分数：", results["distances"])  # 分数越小，相似度越高（默认余弦相似度）
print("文档元数据：", results["metadatas"])

2. 运行结果解读

运行代码后，会输出如下结果（相似度分数可能略有差异，不影响）：

查询结果：
相似文档： [['向量数据库用于存储和检索嵌入向量，核心是相似性查询', 'Chroma是一款轻量级向量数据库，支持Python API', 'Sentence-BERT是常用的文本嵌入模型，可将文本转化为向量']]
文档ID： [['3', '2', '4']]
相似度分数： [[0.123, 0.345, 0.567]]
文档元数据： [[{'category': '概念解释'}, {'category': '向量数据库'}, {'category': '嵌入模型'}]]

• documents：匹配到的相似文本，按相似度从高到低排序；
• ids：相似文本对应的唯一标识；
• distances：相似度分数（范围 0~1），分数越小，与查询文本的语义越相似；
• metadatas：相似文本的附加信息，可用于过滤、分类。

3. 关键说明

① 本示例使用内存模式，程序关闭后，数据会丢失；后续会讲解持久化存储，确保数据长期保存。② Chroma 默认使用自带的嵌入模型（all-MiniLM-L6-v2），自动将文本转化为向量，无需手动调用嵌入模型。

---

四、核心基础：Chroma 核心概念与常用操作

掌握核心概念和常用操作，是灵活使用 Chroma 的关键。本节将详细讲解 Chroma 的核心组件，以及 “增删改查” 等高频操作。

1. 核心概念详解

组件	说明	类比
Client（客户端）	Chroma 的入口，用于创建、管理集合，控制存储模式（内存 / 持久化）	数据库连接
Collection（集合）	存储向量数据的容器，每个集合独立管理数据，可设置元数据和嵌入模型	数据库中的 “表”
Embedding（向量）	文本、图像等转化后的数值序列，Chroma 自动存储和管理	表中的 “字段值”
Metadata（元数据）	每条数据的附加信息（如分类、时间、作者），可用于过滤查询	表中的 “备注字段”

2. 高频操作实战（必掌握）

以下操作均基于 “持久化客户端”（数据长期保存），避免程序关闭后数据丢失，代码可直接复制运行，建议逐行练习。

（1）初始化持久化客户端

持久化模式：将数据保存到本地文件夹，下次启动程序可直接加载，无需重新添加数据。

Python

import chromadb

# 持久化客户端：path参数指定数据保存的文件夹路径（自定义）
# 若文件夹不存在，Chroma会自动创建
client = chromadb.PersistentClient(path="./chroma_data")  # 数据保存在当前目录的chroma_data文件夹

# 后续所有操作，均基于这个持久化客户端

（2）集合操作（创建、查询、删除）

Python

# 1. 创建集合（若集合已存在，会报错，可先判断是否存在）
if "demo_collection" not in [col.name for col in client.list_collections()]:
    collection = client.create_collection(
        name="demo_collection",
        metadata={"description": "演示集合，用于存储文章片段"},
        embedding_function=None  # 使用默认嵌入模型，None表示自动使用内置模型
    )
else:
    # 若集合已存在，直接获取集合
    collection = client.get_collection(name="demo_collection")

# 2. 查询所有集合
all_collections = client.list_collections()
print("所有集合：", [col.name for col in all_collections])

# 3. 删除集合（谨慎操作，删除后数据不可恢复）
# client.delete_collection(name="demo_collection")

（3）数据操作（增、删、改、查）

Python

# ① 新增数据（批量添加，支持多字段）
collection.add(
    ids=["doc1", "doc2", "doc3", "doc4"],  # 唯一标识，不可重复
    documents=[
        "Chroma支持持久化存储，数据可长期保存",
        "相似性查询是向量数据库的核心功能，基于余弦相似度计算",
        "Python是AI开发的主流语言，生态完善",
        "RAG（检索增强生成）是将向量数据库与LLM结合的核心技术"
    ],
    metadatas=[
        {"type": "数据库", "create_time": "2026-03-27"},
        {"type": "概念", "create_time": "2026-03-27"},
        {"type": "编程语言", "create_time": "2026-03-27"},
        {"type": "AI技术", "create_time": "2026-03-27"}
    ]
)

# ② 查询数据（3种常用方式）
# 方式1：按ID查询（精准查询）
id_query = collection.get(ids=["doc1", "doc3"])
print("按ID查询结果：", id_query["documents"])

# 方式2：相似性查询（核心，按语义匹配）
similar_query = collection.query(
    query_texts=["什么是RAG技术？"],
    n_results=2,
    where={"type": "AI技术"}  # 可选：按元数据过滤（只查询AI技术类型的文档）
)
print("相似性查询结果：", similar_query["documents"])

# 方式3：查询所有数据
all_docs = collection.get()
print("所有数据：", all_docs["documents"])

# ③ 修改数据（只能修改metadata和documents，不能修改ids和embeddings）
collection.update(
    ids=["doc1"],  # 要修改的文档ID
    documents=["Chroma支持持久化存储和内存存储，数据可长期保存或临时使用"],  # 新的文档内容
    metadatas=[{"type": "数据库", "create_time": "2026-03-27", "update_time": "2026-03-27"}]  # 新的元数据
)

# ④ 删除数据（按ID删除，批量删除可用列表）
collection.delete(ids=["doc4"])  # 删除ID为doc4的数据
print("删除后的数据：", collection.get()["documents"])

（4）相似性查询的高级用法

结合元数据过滤、批量查询、自定义相似度阈值，满足复杂场景需求：

Python

# 1. 批量查询（同时查询多个文本）
batch_query = collection.query(
    query_texts=["什么是向量数据库？", "Python的应用场景"],
    n_results=2
)
print("批量查询结果：", batch_query["documents"])

# 2. 按元数据过滤查询（多条件过滤）
filtered_query = collection.query(
    query_texts=["数据库相关内容"],
    n_results=2,
    where={
        "$and": [
            {"type": "数据库"},  # 类型为数据库
            {"create_time": "2026-03-27"}  # 创建时间为2026-03-27
        ]
    }
)
print("过滤查询结果：", filtered_query["documents"])

# 3. 手动传入向量查询（无需Chroma自动转化，适合已提前生成向量的场景）
# 假设已通过其他模型生成向量（示例向量，实际需用真实嵌入结果）
query_embedding = [0.1, 0.2, 0.3, 0.4, 0.5]  # 模拟向量（长度需与Chroma嵌入模型一致）
vector_query = collection.query(
    query_embeddings=[query_embedding],
    n_results=2
)
print("向量查询结果：", vector_query["documents"])

---

五、进阶操作：解决 90% 的实际场景问题

学会基础操作后，本节将解决实际使用中常见的问题：自定义嵌入模型、数据批量处理、分页查询、Chroma 服务部署，让你能应对复杂场景。

1. 自定义嵌入模型（替代默认模型）

默认嵌入模型（all-MiniLM-L6-v2）轻量但精度一般，实际场景中可替换为 Sentence-BERT、OpenAI Embedding 等更精准的模型。

Python

# 1. 导入Sentence-BERT模型
from sentence_transformers import SentenceTransformer
from chromadb.utils import embedding_functions

# 2. 初始化自定义嵌入模型（选择常用的all-MiniLM-L12-v2，精度高于默认模型）
sentence_transformer_ef = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="all-MiniLM-L12-v2"  # 模型名称，可更换为其他Sentence-BERT模型
)

# 3. 创建集合时指定自定义嵌入模型
collection = client.create_collection(
    name="custom_embedding_collection",
    embedding_function=sentence_transformer_ef  # 关联自定义嵌入模型
)

# 4. 后续操作与默认模型一致，Chroma会自动使用自定义模型转化向量
collection.add(
    ids=["1", "2"],
    documents=["自定义嵌入模型精度更高，适合复杂场景", "Sentence-BERT是开源的嵌入模型"]
)

# 查询测试
results = collection.query(query_texts=["开源嵌入模型有哪些？"], n_results=1)
print("自定义模型查询结果：", results["documents"])

✨ 提示：若需使用 OpenAI Embedding，需安装 openai 库，并传入 API 密钥，具体可参考 Chroma 官方文档。

2. 批量处理大量数据

当数据量较大（上千条、上万条）时，批量添加 / 查询可提升效率，避免逐条操作耗时：

Python

import random

# 模拟大量数据（100条示例数据）
ids = [f"doc{i}" for i in range(100)]
documents = [f"示例文档{i}：向量数据库的应用场景包括语义搜索、推荐系统等" for i in range(100)]
metadatas = [{"category": "测试数据", "index": i} for i in range(100)]

# 批量添加（一次性添加100条数据，效率远高于逐条添加）
collection.add(
    ids=ids,
    documents=documents,
    metadatas=metadatas
)

# 批量查询（同时查询5个文本，每个文本返回3条相似结果）
query_texts = [f"查询测试{i}" for i in range(5)]
batch_results = collection.query(
    query_texts=query_texts,
    n_results=3
)

print("批量查询结果数量：", len(batch_results["documents"]))  # 输出5，对应5个查询文本

3. 分页查询（处理大量查询结果）

当查询结果较多时，可通过分页获取，避免一次性返回过多数据导致内存占用过大：

Python

# 分页查询：每页返回10条结果，获取第2页（页码从0开始）
page_size = 10  # 每页条数
page_num = 1    # 第2页（0为第1页）

# 1. 先查询所有结果的总数
total_docs = collection.count()  # 获取集合中所有文档的数量
print("总文档数：", total_docs)

# 2. 分页查询（通过offset控制起始位置）
# offset = 页码 * 每页条数
results = collection.query(
    query_texts=["向量数据库的应用"],
    n_results=page_size,
    offset=page_num * page_size
)

print(f"第{page_num+1}页查询结果：", results["documents"])

4. 部署 Chroma 服务（多程序共享）

默认情况下，Chroma 是嵌入式的（仅当前 Python 程序可用），若需多程序、多设备共享 Chroma，可部署为独立服务，通过 HTTP 客户端访问。

# 1. 启动Chroma服务（默认端口8000）
chroma run --path ./chroma_server_data --port 8000

# 2. 客户端连接服务（另一Python程序中执行）
import chromadb

# 连接远程Chroma服务（host为服务部署的IP，port为服务端口）
client = chromadb.HttpClient(host="localhost", port=8000)

# 后续操作与本地客户端一致（创建集合、添加数据、查询等）
collection = client.get_or_create_collection(name="server_collection")
collection.add(ids=["1"], documents=["部署Chroma服务后，多程序可共享数据"])

✅ 提示：若需远程访问，需将 host 改为服务部署的公网 IP，并开放对应端口。

5. 数据导出与导入（备份与迁移）

可将 Chroma 集合中的数据导出为 JSON 格式，用于备份或迁移到其他 Chroma 实例：

Python

import json

# 1. 导出数据（将集合数据导出为JSON文件）
collection = client.get_collection(name="demo_collection")
all_data = collection.get()

# 整理数据格式，便于导出
export_data = {
    "ids": all_data["ids"],
    "documents": all_data["documents"],
    "metadatas": all_data["metadatas"],
    "embeddings": all_data["embeddings"]  # 可选：导出向量数据
}

# 保存为JSON文件
with open("chroma_export.json", "w", encoding="utf-8") as f:
    json.dump(export_data, f, ensure_ascii=False, indent=2)

# 2. 导入数据（从JSON文件导入到新集合）
with open("chroma_export.json", "r", encoding="utf-8") as f:
    import_data = json.load(f)

# 创建新集合，导入数据
new_collection = client.create_collection(name="imported_collection")
new_collection.add(
    ids=import_data["ids"],
    documents=import_data["documents"],
    metadatas=import_data["metadatas"],
    embeddings=import_data["embeddings"]  # 若导出时包含向量，可直接导入
)

print("数据导入成功！")

---

六、高级功能：与 AI 结合（RAG 实战）

Chroma 最核心的应用场景是 RAG（检索增强生成）：将知识库存入 Chroma，结合大语言模型（LLM），实现精准、可控的 AI 问答（避免 LLM 胡言乱语）。本节将结合开源 LLM（Llama 2）或 OpenAI API，实现一个简易的 RAG 问答系统，完整可运行。

1. 准备工作（安装依赖）

# 安装openai库（用于调用OpenAI API，若用开源LLM可跳过）
pip install openai -i https://pypi.tuna.tsinghua.edu.cn/simple
# 安装llama-cpp-python（用于调用开源LLM，如Llama 2，可选）
# pip install llama-cpp-python

2. 基于 OpenAI API 的 RAG 实战（推荐，上手快）

Python

import chromadb
import openai
from chromadb.utils import embedding_functions

# 1. 配置OpenAI API密钥（需自行注册获取）
openai.api_key = "你的OpenAI API密钥"

# 2. 初始化Chroma客户端（持久化）和OpenAI嵌入模型
openai_ef = embedding_functions.OpenAIEmbeddingFunction(
    api_key=openai.api_key,
    model_name="text-embedding-ada-002"  # OpenAI常用嵌入模型
)

client = chromadb.PersistentClient(path="./rag_chroma_data")
collection = client.get_or_create_collection(
    name="rag_knowledge_base",
    embedding_function=openai_ef
)

# 3. 向知识库添加数据（示例：Chroma相关知识）
knowledge_base = [
    "Chroma是一款开源、轻量级的向量数据库，支持Python API，无需复杂部署",
    "Chroma支持两种存储模式：内存模式和持久化模式，持久化模式可将数据保存到本地文件夹",
    "Chroma默认使用all-MiniLM-L6-v2嵌入模型，可替换为Sentence-BERT、OpenAI Embedding等模型",
    "Chroma的核心功能包括：相似性查询、数据增删改查、批量处理、数据导出导入",
    "Chroma可与LLM结合实现RAG（检索增强生成），用于AI问答、语义搜索等场景"
]

# 添加知识库到Chroma
collection.add(
    ids=[f"kb{i}" for i in range(len(knowledge_base))],
    documents=knowledge_base
)

# 4. RAG核心逻辑：检索相似知识 + 调用LLM生成回答
def rag_qa(query):
    # 步骤1：从Chroma中检索与查询最相似的3条知识
    results = collection.query(
        query_texts=[query],
        n_results=3
    )
    # 提取检索到的知识
    retrieved_knowledge = "\n".join(results["documents"][0])
    
    # 步骤2：构造提示词，将检索到的知识传入LLM
    prompt = f"""
    请根据以下知识库内容，回答用户的问题，不要添加知识库之外的信息，确保回答准确、简洁。
    知识库：
    {retrieved_knowledge}
    
    用户问题：{query}
    回答：
    """
    
    # 步骤3：调用OpenAI API生成回答
    response = openai.ChatCompletion.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": prompt}]
    )
    
    return response.choices[0].message.content.strip()

# 5. 测试RAG问答
query1 = "Chroma支持哪些存储模式？"
query2 = "Chroma如何与LLM结合使用？"

print("问题1：", query1)
print("回答1：", rag_qa(query1))
print("\n问题2：", query2)
print("回答2：", rag_qa(query2))

3. 结果说明

运行后，LLM 会基于 Chroma 检索到的知识库内容生成回答，避免脱离知识库的胡言乱语。例如：

问题1：Chrom支持哪些存储模式？
回答1：Chroma支持两种存储模式：内存模式和持久化模式，持久化模式可将数据保存到本地文件夹。

问题2：Chroma如何与LLM结合使用？
回答2：Chroma可与LLM结合实现RAG（检索增强生成），具体方式是将知识库存入Chroma，当用户提出问题时，从Chroma中检索与问题最相似的知识，再将检索到的知识传入LLM，由LLM基于这些知识生成准确回答。

---

七、实战案例：完整项目（文本相似性搜索）

本节将实现一个完整的实战项目：文本相似性搜索系统，支持上传文本、添加到 Chroma 知识库、输入查询文本，返回最相似的文本，可直接用于实际项目。

1. 项目需求

• 支持批量添加文本到知识库（持久化存储）；
• 输入查询文本，返回最相似的 3 条文本；
• 显示每条文本的相似度分数和元数据；
• 支持删除指定文本、清空知识库。

2. 完整代码（可直接运行）

Python

import chromadb
from chromadb.utils import embedding_functions

class SimilaritySearchSystem:
    def __init__(self, collection_name="similarity_search", data_path="./search_data"):
        # 初始化Chroma客户端（持久化）和嵌入模型
        self.client = chromadb.PersistentClient(path=data_path)
        self.embedding_func = embedding_functions.SentenceTransformerEmbeddingFunction(
            model_name="all-MiniLM-L12-v2"
        )
        # 获取或创建集合
        self.collection = self.client.get_or_create_collection(
            name=collection_name,
            embedding_function=self.embedding_func
        )
    
    def add_texts(self, texts, metadatas=None):
        """批量添加文本到知识库"""
        if metadatas is None:
            metadatas = [{"source": "user_upload"} for _ in range(len(texts))]
        # 生成唯一ID（按时间戳+索引，避免重复）
        import time
        ids = [f"text_{int(time.time())}_{i}" for i in range(len(texts))]
        self.collection.add(
            ids=ids,
            documents=texts,
            metadatas=metadatas
        )
        print(f"成功添加{len(texts)}条文本到知识库！")
        return ids
    
    def search_similar(self, query_text, n_results=3):
        """相似性搜索，返回最相似的n条文本"""
        if self.collection.count() == 0:
            return "知识库为空，请先添加文本！"
        results = self.collection.query(
            query_texts=[query_text],
            n_results=n_results
        )
        # 整理结果，便于展示
        output = []
        for i in range(n_results):
            doc = results["documents"][0][i]
            doc_id = results["ids"][0][i]
            score = results["distances"][0][i]
            metadata = results["metadatas"][0][i]
            output.append(f"第{i+1}条（相似度：{score:.3f}，ID：{doc_id}）：")
            output.append(f"文本：{doc}")
            output.append(f"元数据：{metadata}\n")
        return "\n".join(output)
    
    def delete_text(self, doc_id):
        """按ID删除文本"""
        try:
            self.collection.delete(ids=[doc_id])
            return f"成功删除ID为{doc_id}的文本！"
        except Exception as e:
            return f"删除失败：{str(e)}"
    
    def clear_collection(self):
        """清空知识库（谨慎操作）"""
        self.client.delete_collection(name=self.collection.name)
        # 重新创建空集合
        self.collection = self.client.create_collection(
            name=self.collection.name,
            embedding_function=self.embedding_func
        )
        return "知识库已清空！"
    
    def get_collection_info(self):
        """获取知识库信息"""
        count = self.collection.count()
        return f"当前知识库共有{count}条文本，集合名称：{self.collection.name}"

# 测试系统
if __name__ == "__main__":
    # 初始化系统
    search_system = SimilaritySearchSystem()
    
    # 1. 添加文本到知识库
    test_texts = [
        "Python是一门面向对象的编程语言，语法简洁，易于学习",
        "Java是一门跨平台的编程语言，广泛用于企业级开发",
        "JavaScript是一门脚本语言，主要用于前端开发",
        "Go语言是一门高性能的编程语言，适合云计算、微服务开发",
        "Rust语言是一门安全、高效的系统级编程语言，用于底层开发"
    ]
    test_metadatas = [
        {"language": "Python", "type": "编程语言"},
        {"language": "Java", "type": "编程语言"},
        {"language": "JavaScript", "type": "编程语言"},
        {"language": "Go", "type": "编程语言"},
        {"language": "Rust", "type": "编程语言"}
    ]
    search_system.add_texts(test_texts, test_metadatas)
    
    # 2. 查看知识库信息
    print(search_system.get_collection_info())
    
    # 3. 相似性搜索
    query = "用于前端开发的编程语言有哪些？"
    print("搜索结果：")
    print(search_system.search_similar(query, n_results=2))
    
    # 4. 删除指定文本（示例ID，需替换为实际添加的ID）
    # print(search_system.delete_text("text_1711500000_2"))
    
    # 5. 清空知识库（谨慎操作）
    # print(search_system.clear_collection())

3. 项目运行说明

① 运行代码后，会自动创建持久化知识库，添加 5 条编程语言相关的文本；② 输入查询文本 “用于前端开发的编程语言有哪些？”，会返回最相似的 2 条文本（JavaScript 相关）；③ 可通过 add_texts 方法添加自定义文本，通过 delete_text 方法删除指定文本，灵活扩展。

---

八、常见问题避坑指南（新手必看）

1. 数据丢失问题：忘记使用持久化客户端（PersistentClient），使用了默认的内存客户端（Client），程序关闭后数据丢失。解决方案：始终使用 PersistentClient，并指定 path 参数。
2. 嵌入模型不匹配：自定义嵌入模型后，查询时使用了不同的模型，导致相似度查询结果异常。解决方案：创建集合时指定嵌入模型，后续查询、添加数据均使用同一模型。
3. ID 重复报错：添加数据时，ids 重复（Chroma 要求 ids 唯一）。解决方案：生成唯一 ID（如时间戳 + 索引、UUID），避免重复。
4. 查询结果为空：知识库中无数据，或查询文本与知识库内容语义差异过大。解决方案：先添加数据，或调整查询文本，确保语义相关。
5. 安装失败：国内环境安装 Chroma 超时。解决方案：使用国内镜像源（如清华源），或升级 pip 版本（pip install --upgrade pip）。
6. 批量添加数据卡顿：一次性添加上万条数据，导致程序卡顿。解决方案：分批次添加（如每次添加 1000 条），或优化嵌入模型。

---

九、总结与进阶方向

1. 核心总结

• Chroma 的核心逻辑：客户端 → 集合 → 数据（文档 + 向量 + 元数据） → 相似性查询；
• 新手入门优先级：环境搭建 → 持久化客户端 → 集合操作 → 数据增删改查 → 相似性查询；
• 核心优势：轻量、易用、无需复杂部署，完美适配 Python 生态，适合新手和中小型项目。

2. 进阶方向

1. 优化嵌入模型：使用更精准的模型（如 text-embedding-3-large、Sentence-BERT 的 large 版本）；
2. 性能优化：学习 Chroma 的索引机制，优化相似性查询速度，应对大规模数据；
3. 多模态支持：结合图像嵌入模型，实现图像相似性检索；
4. 生产环境部署：学习 Chroma 集群部署、备份策略，用于生产环境；
5. 深入 RAG：结合 LangChain、LLaMA 2 等工具，实现更复杂的 RAG 系统（如多轮对话、知识库更新）。

按照本教程学习，你已经掌握了 Chroma 的核心用法，能够独立完成向量存储、相似性查询、RAG 等实战需求。后续可结合具体场景，灵活扩展功能，解锁更多向量数据库的应用价值！