ChromaDB02-代码实战
运行ChromaDB向量数据库的过程中有遇到一些问题，在此记录过程中遇到的问题和解决办法，代码仓库：https://gitee.com/enzoism/kumi_chroma_db.git
1-核心知识
- 1）如果我没有ChromaDB服务，我要怎么进行测试
- 使用【内存模式】进行测试
- 使用【持久化模式】进行测试
- 2）我安装了ChromaDB服务后，我要怎么进行测试->使用【客户端模式】进行测试
- 3）向量数据库操作->涉及到embedding的方法
- 使用假的embedding方法
- 使用真的embedding方法->如何解决模型的下载问题
2-动手实操
1-ChromaDB内存模式
- 直接连接ChromaDB进行数据【插入和 查询】
python
import chromadb
try:
# 方法1：使用默认配置连接（内存模式）
client = chromadb.Client()
print("✓ ChromaDB 内存模式连接成功")
# 方法2：使用持久化存储（持久化模式）
# client = chromadb.PersistentClient(path="./chroma_db")
# print("✅ 已连接到 ChromaDB (使用持久化存储)")
# 方法3：使用服务器配置连接（服务器模式）
# client = chromadb.HttpClient(host='localhost', port=8000)
# print("✓ 成功连接到 ChromaDB 服务器")
# 创建测试集合
collection = client.get_or_create_collection(name="test_collection_01")
# 获取服务器版本信息
version = client.get_version()
print(f"服务器版本: {version}")
# 列出所有集合
collections = client.list_collections()
print(f"当前集合数量: {len(collections)}-{collections}")
# 添加测试数据
collection.add(
documents=["测试文档"],
ids=["test_id_1"],
metadatas={"source": "test"}
)
print(f"✓ 数据写入测试通过")
# 查询验证
results = collection.query(
query_texts=["测试"],
n_results=1
)
print(f"✓ 数据查询测试通过-{results}")
except Exception as e:
print(f"✗ 连接测试失败: {e}")- 日志打印
shell
✓ ChromaDB 内存模式连接成功
服务器版本: 1.4.0
当前集合数量: 1-[Collection(name=test_collection_01)]
✓ 数据写入测试通过
✓ 数据查询测试通过-{'ids': [['test_id_1']], 'embeddings': None, 'documents': [['测试文档']], 'uris': None, 'included': ['metadatas', 'documents', 'distances'], 'data': None, 'metadatas': [[{'source': 'test'}]], 'distances': [[0.9398118257522583]]}2-ChromaDB持久化模式
- 直接连接ChromaDB进行数据【插入和 查询】
python
import chromadb
try:
# 方法1：使用默认配置连接（内存模式）
# client = chromadb.Client()
# print("✓ ChromaDB 内存模式连接成功")
# 方法2：使用持久化存储（持久化模式）
client = chromadb.PersistentClient(path="./chroma_db")
print("✅ 已连接到 ChromaDB (使用持久化存储)")
# 方法3：使用服务器配置连接（服务器模式）
# client = chromadb.HttpClient(host='localhost', port=8000)
# print("✓ 成功连接到 ChromaDB 服务器")
# 其他还是相同的代码，在此出省略。。。3-ChromaDB客户端模式
- 直接连接ChromaDB进行数据【插入和 查询】
python
import chromadb
try:
# 方法1：使用默认配置连接（内存模式）
# client = chromadb.Client()
# print("✓ ChromaDB 内存模式连接成功")
# 方法2：使用持久化存储（持久化模式）
# client = chromadb.PersistentClient(path="./chroma_db")
# print("✅ 已连接到 ChromaDB (使用持久化存储)")
# 方法3：使用服务器配置连接（服务器模式）
client = chromadb.HttpClient(host='localhost', port=8000)
print("✓ 成功连接到 ChromaDB 服务器")
# 其他还是相同的代码，在此出省略。。。4-ChromaDB向量写入
1-模拟embedding向量写入
python
#!/usr/bin/env python3
"""
ChromaDB 最小化 Demo
演示 ChromaDB 的核心功能：创建集合、插入数据、向量查询
"""
import chromadb
def main():
print("=" * 60)
print("ChromaDB 最小化演示程序")
print("=" * 60)
# ========================================
# 1. 连接到 ChromaDB 服务器
# ========================================
print("\n📡 步骤 1: 连接到 ChromaDB 服务器")
print("-" * 60)
# 方法1：使用默认配置连接（内存模式）
# client = chromadb.Client()
# print("✓ ChromaDB 内存模式连接成功")
# 方法2：使用持久化存储（持久化模式）
# client = chromadb.PersistentClient(path="./chroma_db")
# print("✅ 已连接到 ChromaDB (使用持久化存储)")
# 方法3：使用服务器配置连接（服务器模式）
client = chromadb.HttpClient(host='localhost', port=8000)
print("✓ 成功连接到 ChromaDB 服务器")
# ========================================
# 2. 创建集合（Collection）
# ========================================
print("\n📚 步骤 2: 创建集合")
print("-" * 60)
collection_name = "demo_knowledge_base"
# 检查并删除已存在的集合
try:
client.delete_collection(name=collection_name)
print(f"⚠️ 已删除已存在的集合 '{collection_name}'")
except:
pass
# 创建新集合
collection = client.create_collection(
name=collection_name,
metadata={"description": "演示知识库"}
)
print(f"✅ 成功创建集合: {collection_name}")
# ========================================
# 3. 准备演示数据
# ========================================
print("\n📝 步骤 3: 准备演示数据")
print("-" * 60)
# 模拟的文档数据（实际应用中应使用真实的 embedding 模型）
documents = [
"Python 是一种高级编程语言，易学易用",
"JavaScript 是 Web 开发的核心语言",
"ChromaDB 是一个开源的向量数据库",
"向量数据库用于存储和检索高维向量",
"机器学习模型将文本转换为向量表示"
]
# 为演示目的，使用简单的伪造向量（3维）
# 实际应用中应使用 embedding 模型（如 OpenAI embeddings）
embeddings = [
[0.1, 0.2, 0.3], # Python 文档的向量
[0.4, 0.5, 0.6], # JavaScript 文档的向量
[0.7, 0.8, 0.9], # ChromaDB 文档的向量
[0.2, 0.3, 0.4], # 向量数据库文档的向量
[0.6, 0.7, 0.8], # 机器学习文档的向量
]
# 元数据
metadatas = [
{"category": "编程语言", "popularity": 10},
{"category": "编程语言", "popularity": 9},
{"category": "数据库", "popularity": 8},
{"category": "数据库", "popularity": 7},
{"category": "人工智能", "popularity": 9},
]
# 文档 ID
ids = ["doc1", "doc2", "doc3", "doc4", "doc5"]
print(f"✅ 已准备 {len(documents)} 条文档")
for i, doc in enumerate(documents, 1):
print(f" {i}. {doc}")
# ========================================
# 4. 插入数据到集合
# ========================================
print("\n➕ 步骤 4: 插入数据到集合")
print("-" * 60)
collection.add(
documents=documents,
embeddings=embeddings,
metadatas=metadatas,
ids=ids
)
print(f"✅ 成功插入 {len(documents)} 条文档到集合")
# 显示集合统计信息
count = collection.count()
print(f"📊 集合中文档总数: {count}")
# ========================================
# 5. 向量查询
# ========================================
print("\n🔍 步骤 5: 执行向量查询")
print("-" * 60)
# MOCK查询向量（模拟查询"编程语言相关的内容"）->当前的embedding是我mock的，不是真实计算的
query_embedding = [[0.15, 0.25, 0.35]] # 与 doc1 和 doc2 相似度较高
# 执行查询
results = collection.query(
query_embeddings=query_embedding,
n_results=3, # 返回最相似的前 3 个结果
include=["documents", "metadatas", "distances"]
)
print(f"✅ 查询完成，找到 {len(results['ids'][0])} 个相似结果")
print("\n查询结果（按相似度排序）：")
for i in range(len(results['ids'][0])):
doc_id = results['ids'][0][i]
document = results['documents'][0][i]
distance = results['distances'][0][i]
metadata = results['metadatas'][0][i]
# ChromaDB 使用 L2 距离，距离越小越相似
similarity_score = 1 / (1 + distance)
print(f"\n 📄 结果 #{i + 1}")
print(f" ID: {doc_id}")
print(f" 内容: {document}")
print(f" 类别: {metadata['category']}")
print(f" 距离: {distance:.4f}")
print(f" 相似度分数: {similarity_score:.4f}")
# ========================================
# 6. 元数据过滤查询
# ========================================
print("\n🎯 步骤 6: 元数据过滤查询")
print("-" * 60)
# 只查询"数据库"类别的文档
filtered_results = collection.query(
query_embeddings=query_embedding,
n_results=5,
where={"category": "数据库"},
include=["documents", "metadatas", "distances"]
)
print(f"✅ 过滤查询完成，类别='数据库'")
print(f" 找到 {len(filtered_results['ids'][0])} 个结果")
for i in range(len(filtered_results['ids'][0])):
doc_id = filtered_results['ids'][0][i]
document = filtered_results['documents'][0][i]
metadata = filtered_results['metadatas'][0][i]
print(f"\n 📄 {doc_id}: {document}：{metadata}")
# ========================================
# 7. 获取和更新文档
# ========================================
print("\n📖 步骤 7: 获取和更新文档")
print("-" * 60)
# 获取单个文档
doc = collection.get(
ids=["doc1"],
include=["documents", "metadatas"]
)
print(f"✅ 获取文档 doc1: {doc['documents'][0]}")
# 更新文档
collection.update(
embeddings=list(embeddings[0]),
ids=["doc1"],
documents=["Python 是一种优雅的编程语言，易学易用且功能强大V2"],
metadatas=[{"category": "编程语言", "popularity": 10}]
)
print("✅ 已更新文档 doc1")
# 验证更新
updated_doc = collection.get(ids=["doc1"], include=["documents"])
print(f" 更新后的内容: {updated_doc['documents'][0]}")
# ========================================
# 8. 删除文档
# ========================================
print("\n🗑️ 步骤 8: 删除文档")
print("-" * 60)
count_before = collection.count()
collection.delete(ids=["doc5"])
count_after = collection.count()
print(f"✅ 已删除文档 doc5")
print(f" 删除前文档数: {count_before}")
print(f" 删除后文档数: {count_after}")
# ========================================
# 总结
# ========================================
print("\n" + "=" * 60)
print("✨ 演示完成！")
print("=" * 60)
print("\n📌 核心功能总结:")
print(" ✓ 连接到 ChromaDB（持久化存储）")
print(" ✓ 创建和管理集合")
print(" ✓ 插入向量数据")
print(" ✓ 向量相似度查询")
print(" ✓ 元数据过滤")
print(" ✓ 获取、更新和删除文档")
print("\n💾 数据已保存在 ./chroma_db 目录中")
print("🔄 可以修改代码尝试不同的查询和操作")
print()
if __name__ == "__main__":
try:
main()
except Exception as e:
print(f"\n❌ 错误: {e}")
import traceback
traceback.print_exc()
print("\n💡 提示: 请确保已安装 chromadb:")
print(" pip install chromadb")- 日志打印
shell
ChromaDB 最小化演示程序
============================================================
📡 步骤 1: 连接到 ChromaDB 服务器
------------------------------------------------------------
✓ 成功连接到 ChromaDB 服务器
📚 步骤 2: 创建集合
------------------------------------------------------------
⚠️ 已删除已存在的集合 'demo_knowledge_base'
✅ 成功创建集合: demo_knowledge_base
📝 步骤 3: 准备演示数据
------------------------------------------------------------
✅ 已准备 5 条文档
1. Python 是一种高级编程语言，易学易用
2. JavaScript 是 Web 开发的核心语言
3. ChromaDB 是一个开源的向量数据库
4. 向量数据库用于存储和检索高维向量
5. 机器学习模型将文本转换为向量表示
➕ 步骤 4: 插入数据到集合
------------------------------------------------------------
✅ 成功插入 5 条文档到集合
📊 集合中文档总数: 5
🔍 步骤 5: 执行向量查询
------------------------------------------------------------
✅ 查询完成，找到 3 个相似结果
查询结果（按相似度排序）：
📄 结果 #1
ID: doc1
内容: Python 是一种高级编程语言，易学易用
类别: 编程语言
距离: 0.0075
相似度分数: 0.9926
📄 结果 #2
ID: doc4
内容: 向量数据库用于存储和检索高维向量
类别: 数据库
距离: 0.0075
相似度分数: 0.9926
📄 结果 #3
ID: doc2
内容: JavaScript 是 Web 开发的核心语言
类别: 编程语言
距离: 0.1875
相似度分数: 0.8421
🎯 步骤 6: 元数据过滤查询
------------------------------------------------------------
✅ 过滤查询完成，类别='数据库'
找到 2 个结果
📄 doc4: 向量数据库用于存储和检索高维向量：{'popularity': 7, 'category': '数据库'}
📄 doc3: ChromaDB 是一个开源的向量数据库：{'popularity': 8, 'category': '数据库'}
📖 步骤 7: 获取和更新文档
------------------------------------------------------------
✅ 获取文档 doc1: Python 是一种高级编程语言，易学易用
✅ 已更新文档 doc1
更新后的内容: Python 是一种优雅的编程语言，易学易用且功能强大V2
🗑️ 步骤 8: 删除文档
------------------------------------------------------------
✅ 已删除文档 doc5
删除前文档数: 5
删除后文档数: 4
============================================================
✨ 演示完成！
============================================================
📌 核心功能总结:
✓ 连接到 ChromaDB（持久化存储）
✓ 创建和管理集合
✓ 插入向量数据
✓ 向量相似度查询
✓ 元数据过滤
✓ 获取、更新和删除文档
💾 数据已保存在 ./chroma_db 目录中
🔄 可以修改代码尝试不同的查询和操作2-先解决模型下载问题
- 尝试用国内的源来替代HuggingFace快速下载模型
python
import os
# 设置模型下载的镜像地址
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
# 导入 SentenceTransformer
from sentence_transformers import SentenceTransformer
# 下载模型并打印相关信息
model = SentenceTransformer('all-MiniLM-L6-v2')
# 打印分隔线
print(f"✅ 模型已经成功下载")- 如果想看详细点，配置logging的日志即可
python
import logging
import os
# 设置日志级别为DEBUG，以便打印出详细的下载信息
logging.basicConfig(level=logging.DEBUG)
# 设置模型下载的镜像地址
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
# 导入 SentenceTransformer
from sentence_transformers import SentenceTransformer
# 下载模型并打印相关信息
model = SentenceTransformer('all-MiniLM-L6-v2')
# 打印分隔线
print(f"✅ 模型已经成功下载")3-真实embedding向量写入
python
#!/usr/bin/env python3
"""
ChromaDB 最小化 Demo
演示 ChromaDB 的核心功能：创建集合、插入数据、向量查询
"""
import os
# 设置模型下载的镜像地址-必须配置（否则模型下载不了）
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
# 导入 ChromaDB
import chromadb
from sentence_transformers import SentenceTransformer # 导入 SentenceTransformer
def main():
print("=" * 60)
print("ChromaDB 最小化演示程序")
print("=" * 60)
# ========================================
# 1. 连接到 ChromaDB 服务器
# ========================================
print("\n📡 步骤 1: 连接到 ChromaDB 服务器")
print("-" * 60)
# 方法1：使用默认配置连接（内存模式）
# client = chromadb.Client()
# print("✓ ChromaDB 内存模式连接成功")
# 方法2：使用持久化存储（持久化模式）
# client = chromadb.PersistentClient(path="./chroma_db")
# print("✅ 已连接到 ChromaDB (使用持久化存储)")
# 方法3：使用服务器配置连接（服务器模式）
client = chromadb.HttpClient(host='localhost', port=8000)
print("✓ 成功连接到 ChromaDB 服务器")
# ========================================
# 2. 创建集合（Collection）
# ========================================
print("\n📚 步骤 2: 创建集合")
print("-" * 60)
collection_name = "demo_knowledge_base"
# 检查并删除已存在的集合
try:
client.delete_collection(name=collection_name)
print(f"⚠️ 已删除已存在的集合 '{collection_name}'")
except:
pass
# 创建新集合
collection = client.create_collection(
name=collection_name,
metadata={"description": "演示知识库"}
)
print(f"✅ 成功创建集合: {collection_name}")
# ========================================
# 3. 准备演示数据
# ========================================
print("\n📝 步骤 3: 准备演示数据")
print("-" * 60)
# 模拟的文档数据
documents = [
"Python 是一种高级编程语言，易学易用",
"JavaScript 是 Web 开发的核心语言",
"ChromaDB 是一个开源的向量数据库",
"向量数据库用于存储和检索高维向量",
"机器学习模型将文本转换为向量表示"
]
# 使用 all-MiniLM-L6-v2 模型生成 embeddings
model = SentenceTransformer('all-MiniLM-L6-v2') # 加载模型
embeddings = model.encode(documents) # 生成 embeddings
# 元数据
metadatas = [
{"category": "编程语言", "popularity": 10},
{"category": "编程语言", "popularity": 9},
{"category": "数据库", "popularity": 8},
{"category": "数据库", "popularity": 7},
{"category": "人工智能", "popularity": 9},
]
# 文档 ID
ids = ["doc1", "doc2", "doc3", "doc4", "doc5"]
print(f"✅ 已准备 {len(documents)} 条文档")
for i, doc in enumerate(documents, 1):
print(f" {i}. {doc}")
# ========================================
# 4. 插入数据到集合
# ========================================
print("\n➕ 步骤 4: 插入数据到集合")
print("-" * 60)
collection.add(
documents=documents,
embeddings=embeddings,
metadatas=metadatas,
ids=ids
)
print(f"✅ 成功插入 {len(documents)} 条文档到集合")
# 显示集合统计信息
count = collection.count()
print(f"📊 集合中文档总数: {count}")
# ========================================
# 5. 向量查询
# ========================================
print("\n🔍 步骤 5: 执行向量查询")
print("-" * 60)
# 查询向量（模拟查询"编程语言相关的内容"）
query_embedding = model.encode(["编程语言"]) # 使用模型生成查询向量
# 执行查询
results = collection.query(
query_embeddings=query_embedding,
n_results=3, # 返回最相似的前 3 个结果
include=["documents", "metadatas", "distances"]
)
print(f"✅ 查询完成，找到 {len(results['ids'][0])} 个相似结果")
print("\n查询结果（按相似度排序）：")
for i in range(len(results['ids'][0])):
doc_id = results['ids'][0][i]
document = results['documents'][0][i]
distance = results['distances'][0][i]
metadata = results['metadatas'][0][i]
# ChromaDB 使用 L2 距离，距离越小越相似
similarity_score = 1 / (1 + distance)
print(f"\n 📄 结果 #{i + 1}")
print(f" ID: {doc_id}")
print(f" 内容: {document}")
print(f" 类别: {metadata['category']}")
print(f" 距离: {distance:.4f}")
print(f" 相似度分数: {similarity_score:.4f}")
# ========================================
# 6. 元数据过滤查询
# ========================================
print("\n🎯 步骤 6: 元数据过滤查询")
print("-" * 60)
# 只查询"数据库"类别的文档
filtered_results = collection.query(
query_embeddings=query_embedding,
n_results=5,
where={"category": "数据库"},
include=["documents", "metadatas", "distances"]
)
print(f"✅ 过滤查询完成，类别='数据库'")
print(f" 找到 {len(filtered_results['ids'][0])} 个结果")
for i in range(len(filtered_results['ids'][0])):
doc_id = filtered_results['ids'][0][i]
document = filtered_results['documents'][0][i]
metadata = filtered_results['metadatas'][0][i]
print(f"\n 📄 {doc_id}: {document}：{metadata}")
# ========================================
# 7. 获取和更新文档
# ========================================
print("\n📖 步骤 7: 获取和更新文档")
print("-" * 60)
# 获取单个文档
doc = collection.get(
ids=["doc1"],
include=["documents", "metadatas"]
)
print(f"✅ 获取文档 doc1: {doc['documents'][0]}")
# 更新文档
collection.update(
ids=["doc1"],
documents=["Python 是一种优雅的编程语言，易学易用且功能强大"],
metadatas=[{"category": "编程语言", "popularity": 10}]
)
print("✅ 已更新文档 doc1")
# 验证更新
updated_doc = collection.get(ids=["doc1"], include=["documents"])
print(f" 更新后的内容: {updated_doc['documents'][0]}")
# ========================================
# 8. 删除文档
# ========================================
print("\n🗑️ 步骤 8: 删除文档")
print("-" * 60)
count_before = collection.count()
collection.delete(ids=["doc5"])
count_after = collection.count()
print(f"✅ 已删除文档 doc5")
print(f" 删除前文档数: {count_before}")
print(f" 删除后文档数: {count_after}")
# ========================================
# 总结
# ========================================
print("\n" + "=" * 60)
print("✨ 演示完成！")
print("=" * 60)
print("\n📌 核心功能总结:")
print(" ✓ 连接到 ChromaDB（持久化存储）")
print(" ✓ 创建和管理集合")
print(" ✓ 插入向量数据")
print(" ✓ 向量相似度查询")
print(" ✓ 元数据过滤")
print(" ✓ 获取、更新和删除文档")
print("\n💾 数据已保存在 ./chroma_db 目录中")
print("🔄 可以修改代码尝试不同的查询和操作")
print()
if __name__ == "__main__":
try:
main()
except Exception as e:
print(f"\n❌ 错误: {e}")
import traceback
traceback.print_exc()
print("\n💡 提示: 请确保已安装 chromadb 和 sentence-transformers:")
print(" pip install chromadb sentence-transformers")