Chroma 是一款輕量級、開源的向量數據庫，專為 AI Agent、RAG（檢索增強生成）等場景設計，以“極簡易用、無需複雜運維、原生支持嵌入（Embedding）”為核心特點，是 AI Agent 記憶系統中實現長期記憶存儲的首選工具之一。本教程基於 Chroma 官方文檔（v0.5.x）整理，從環境搭建到實戰應用，覆蓋新手入門的全核心流程，所有代碼均可直接運行。

一、Chroma 核心定位與優勢（官方定義）

Chroma 官方對自身的定位是：“The AI-native open-source embedding database”（原生適配 AI 的開源嵌入數據庫），核心優勢：

1. 極簡部署：支持本地 Python 庫、Docker 容器、雲服務三種部署方式，新手5分鐘即可啓動；
2. 原生嵌入支持：內置輕量級嵌入模型（無需依賴外部 API），也可無縫集成 OpenAI、HuggingFace 等第三方嵌入模型；
3. 面向開發者友好：API 設計簡潔，無需數據庫運維經驗，專注於“存儲向量、檢索向量”核心需求；
4. 適配 AI Agent：支持按元數據過濾（如用户 ID、記憶類型）、動態更新向量，完美匹配記憶系統的“寫入-檢索-更新-遺忘”全流程。

二、環境搭建（官方推薦兩種方式）

方式1：本地 Python 安裝（推薦新手）

Chroma 支持 Python 3.8+，通過 pip 一鍵安裝：

# 基礎安裝（含核心功能）
pip install chromadb

# 完整安裝（含內置嵌入模型、可視化工具）
pip install "chromadb[all]"

驗證安裝成功：

import chromadb
print(f"Chroma 版本：{chromadb.__version__}")  # 輸出版本號即成功

方式2：Docker 部署（適合生產/多環境共享）

官方提供預構建鏡像，無需配置 Python 環境：

# 拉取官方鏡像
docker pull chromadb/chroma:latest

# 啓動容器（默認端口8000，數據持久化到本地./chroma_data）
docker run -p 8000:8000 -v ./chroma_data:/chroma/chroma_data chromadb/chroma:latest

驗證容器啓動成功：訪問 http://localhost:8000/api/v1/heartbeat，返回 {"heartbeat": "string"} 即成功。

三、Chroma 核心概念（官方術語）

在使用前需理解 4 個核心概念，對應 AI Agent 記憶系統的存儲邏輯：

四、基礎操作（官方核心 API）

以下示例基於本地 Python 客户端，所有操作均為 Chroma 官方推薦用法。

1. 初始化客户端

Chroma 支持兩種客户端模式：

import chromadb

# 模式1：內存模式（數據僅存於內存，程序退出丟失，適合測試）
client = chromadb.Client()

# 模式2：持久化模式（數據保存到本地文件，適合生產）
client = chromadb.PersistentClient(path="./chroma_persist")  # path 為數據存儲路徑

# 模式3：遠程客户端（連接 Docker 部署的 Chroma 服務）
client = chromadb.HttpClient(host="localhost", port=8000)

2. 創建/獲取 Collection

Collection 是操作的核心載體，創建時可指定嵌入模型（默認用內置的 all-MiniLM-L6-v2）：

# 創建 Collection（若已存在則自動獲取）
collection = client.create_collection(
    name="agent_memory",  # Collection 名稱
    metadata={"description": "AI Agent 長期記憶存儲"},  # 可選描述
    get_or_create=True  # 關鍵：避免重複創建
)

# 查看所有 Collection
print("所有 Collection：", client.list_collections())

# 獲取指定 Collection
collection = client.get_collection(name="agent_memory")

3. 添加記憶數據（寫入長期記憶）

Chroma 支持兩種添加方式：自動生成向量（內置模型）、手動傳入向量（如 OpenAI 嵌入）。

方式1：自動生成向量（新手首選）

# 準備數據：文檔+元數據+唯一ID（ID 可選，Chroma 會自動生成）
documents = [
    "用户喜歡印象派藝術，計劃2025年7月去巴黎旅行",
    "用户對咖啡因敏感，不喝含咖啡的飲料",
    "用户的生日是3月5日，偏好收到實用型禮物"
]
metadatas = [
    {"user_id": "user123", "memory_type": "preference", "timestamp": "2025-01-07"},
    {"user_id": "user123", "memory_type": "preference", "timestamp": "2025-01-07"},
    {"user_id": "user123", "memory_type": "basic_info", "timestamp": "2025-01-07"}
]
ids = ["mem1", "mem2", "mem3"]  # 自定義唯一ID，便於後續更新/刪除

# 添加到 Collection
collection.add(
    documents=documents,
    metadatas=metadatas,
    ids=ids
)

# 查看 Collection 統計信息
print("記憶條目數量：", collection.count())  # 輸出 3

方式2：手動傳入向量（適配第三方嵌入模型）

若需用 OpenAI 等高精度嵌入模型，可手動生成向量後傳入：

from openai import OpenAI

# 初始化 OpenAI 客户端
openai_client = OpenAI(api_key="your-openai-api-key")

# 生成嵌入向量
def get_openai_embeddings(texts):
    response = openai_client.embeddings.create(
        input=texts,
        model="text-embedding-3-small"
    )
    return [item.embedding for item in response.data]

# 生成向量
embeddings = get_openai_embeddings(documents)

# 手動傳入向量添加數據
collection.add(
    documents=documents,
    metadatas=metadatas,
    ids=ids,
    embeddings=embeddings  # 手動指定向量
)

4. 檢索相關記憶（核心：語義相似性搜索）

檢索是 AI Agent 記憶系統的核心操作，Chroma 支持“純語義檢索”“元數據過濾+語義檢索”兩種方式。

方式1：純語義檢索（按相似度召回）

# 檢索與“巴黎旅行推薦”相關的記憶（Top 2）
results = collection.query(
    query_texts=["巴黎旅行推薦"],  # 查詢文本（可傳多個）
    n_results=2  # 返回最相似的2條
)

# 解析結果
print("檢索到的記憶ID：", results["ids"])  # 輸出 ["mem1", ...]
print("記憶內容：", results["documents"])   # 輸出對應的文本
print("相似度評分：", results["distances"])  # 距離越小，相似度越高（Chroma 默認用 L2 距離）

方式2：元數據過濾+語義檢索（精準定位）

AI Agent 中需確保“僅檢索當前用户的記憶”，可通過元數據過濾實現：

# 檢索 user123 的、與“巴黎旅行”相關的偏好類記憶
results = collection.query(
    query_texts=["巴黎旅行"],
    n_results=1,
    where={  # 元數據過濾條件（支持 ==、!=、>、<、contains 等）
        "user_id": "user123",
        "memory_type": "preference"
    }
)

print("過濾後的記憶內容：", results["documents"])  # 僅輸出 mem1

5. 更新記憶（修正錯誤/過期記憶）

當用户偏好變更時，需更新已有記憶：

# 更新 mem1 的內容（用户旅行時間改為8月）
collection.update(
    id="mem1",
    document="用户喜歡印象派藝術，計劃2025年8月去巴黎旅行",
    metadata={"user_id": "user123", "memory_type": "preference", "timestamp": "2025-01-08"}
)

# 驗證更新結果
updated = collection.get(ids=["mem1"])
print("更新後的記憶：", updated["documents"])  # 輸出修改後的內容

6. 刪除記憶（遺忘無效/敏感記憶）

支持按 ID、元數據過濾刪除：

# 方式1：按 ID 刪除
collection.delete(ids=["mem3"])  # 刪除生日相關記憶
print("刪除後條目數：", collection.count())  # 輸出 2

# 方式2：按元數據過濾刪除（刪除所有偏好類記憶）
collection.delete(
    where={"memory_type": "preference"}
)
print("過濾刪除後條目數：", collection.count())  # 輸出 0

7. 批量獲取記憶（全量/過濾查詢）

# 獲取所有記憶
all_memories = collection.get()
print("全量記憶：", all_memories["documents"])

# 按元數據過濾獲取
filtered_memories = collection.get(
    where={"user_id": "user123"}
)
print("過濾後的記憶：", filtered_memories["documents"])

五、實戰案例：Chroma 集成到 AI Agent 記憶系統

以下是官方推薦的“Chroma + OpenAI”構建極簡 AI Agent 記憶系統的示例，完整實現“記住用户偏好→跨會話複用”：

import chromadb
from openai import OpenAI

# 1. 初始化組件
chroma_client = chromadb.PersistentClient(path="./agent_memory_db")
openai_client = OpenAI(api_key="your-openai-api-key")

# 2. 創建/獲取記憶 Collection
memory_collection = chroma_client.get_or_create_collection(
    name="travel_agent_memory",
    metadata={"description": "旅行Agent長期記憶"}
)

# 3. 核心函數：寫入記憶
def save_agent_memory(user_id, content, memory_type="preference"):
    # 生成唯一ID（用户ID+時間戳）
    import time
    mem_id = f"{user_id}_{int(time.time())}"
    # 生成OpenAI嵌入向量
    embedding = openai_client.embeddings.create(
        input=[content],
        model="text-embedding-3-small"
    ).data[0].embedding
    # 寫入Chroma
    memory_collection.add(
        documents=[content],
        metadatas=[{"user_id": user_id, "memory_type": memory_type}],
        ids=[mem_id],
        embeddings=[embedding]
    )
    print(f"記憶寫入成功，ID：{mem_id}")

# 4. 核心函數：檢索記憶
def retrieve_agent_memory(user_id, query, n_results=3):
    # 生成查詢向量
    query_embedding = openai_client.embeddings.create(
        input=[query],
        model="text-embedding-3-small"
    ).data[0].embedding
    # 檢索（僅當前用户）
    results = memory_collection.query(
        query_embeddings=[query_embedding],  # 手動傳入查詢向量
        n_results=n_results,
        where={"user_id": user_id}
    )
    # 格式化結果
    return "\n".join([f"- {doc}" for doc in results["documents"][0]]) if results["documents"][0] else "無相關記憶"

# 5. 核心函數：Agent 響應生成
def agent_respond(user_id, query):
    # 檢索相關記憶
    relevant_memories = retrieve_agent_memory(user_id, query)
    # 構建Prompt（融入記憶）
    prompt = f"""
    你是一個旅行助手Agent，需結合用户的長期記憶回答問題。
    用户長期記憶：
    {relevant_memories}
    
    用户當前問題：{query}
    
    要求：基於記憶回答，無記憶時直接回答，不編造信息。
    """
    # 生成響應
    response = openai_client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": prompt}]
    ).choices[0].message.content
    # 若查詢包含偏好/計劃，自動寫入記憶
    if any(keyword in query for keyword in ["喜歡", "計劃", "偏好", "想去"]):
        save_agent_memory(user_id, query)
    return response

# 6. 測試交互
USER_ID = "user123"

# 第一輪對話：用户告知偏好（自動寫入記憶）
query1 = "我喜歡印象派藝術，計劃2025年8月去巴黎旅行"
response1 = agent_respond(USER_ID, query1)
print(f"Agent響應1：{response1}")

# 第二輪對話：跨會話複用記憶
query2 = "推薦巴黎適合我的景點"
response2 = agent_respond(USER_ID, query2)
print(f"Agent響應2：{response2}")  # 會推薦奧賽博物館等印象派相關景點

六、Chroma 官方進階資源與常見問題

1. 官方核心資源

• 官方文檔：https://docs.trychroma.com/（最權威，含API全解析、高級功能）；
• GitHub 倉庫：https://github.com/chroma-core/chroma（源碼、示例、問題反饋）；
• 官方教程視頻：https://www.youtube.com/@ChromaDB（英文，實操演示）；
• 可視化工具：Chroma 內置 chroma ui 命令，啓動後可通過網頁查看/管理 Collection（需安裝 chromadb[all]）。

2. 新手常見問題（官方解答）

總結

核心關鍵點回顧

1. Chroma 核心價值：輕量級、易部署，專為 AI 場景設計，是 Agent 記憶系統長期記憶存儲的首選工具；
2. 核心操作流程：創建 Collection → 添加文檔/向量/元數據 → 按語義+元數據檢索 → 更新/刪除記憶；
3. 實戰關鍵：通過元數據過濾（如 user_id）確保記憶隔離，結合第三方嵌入模型提升檢索精度。

掌握以上內容，即可基於 Chroma 快速搭建 AI Agent 的長期記憶系統，後續可進一步學習 Chroma 的高級功能（如批量操作、索引優化、多模態支持），適配更復雜的 Agent 場景。