activeloopai/deeplake · 上手攻略

仓库：activeloopai/deeplake
链接：https://github.com/activeloopai/deeplake
分类：ai（主分类：agent，副分类：multimodal）
作者：Tom
更新：2026-07-08

是什么

Deep Lake 是 AI 数据运行时（AI Data Runtime），由 Activeloop 提供。其核心定位是：专为 AI 应用设计的多模态数据库，同时支持向量检索、数据版本控制和多模态原始数据存储。

与只存 embedding 的向量数据库不同，Deep Lake 可以存任意类型的原始数据——图片、视频、音频、PDF、文本、embedding 向量——并在同一套 API 下完成检索和训练数据供给。

最新版本（v4）是面向云原生和 Agent 场景重新设计的，提供 Serverless Postgres + 多模态 DataLake，支持 S3/GCS/Azure 等多种存储后端。已被 Intel、Bayer Radiology、Matterport、红十字会、耶鲁大学、牛津大学等机构使用。

解决什么问题

LLM 应用的数据存储：embedding + 原始文本/文档统一存储，支持向量相似搜索
多模态训练数据管理：图片、视频、音频的版本控制、流式加载、PyTorch/TensorFlow 原生集成
Agent 记忆存储：为 Agent 提供持久化记忆存储，支持结构化查询和向量检索
数据版本控制：像 Git 一样管理数据集，支持分支、回滚、Lineage 追踪
数据可视化：直接在 Web App 中预览带标注的可视化数据集
数据合规：多云存储，数据在自己云里，不需要全部上传到第三方服务

快速安装

# 基础安装
pip install deeplake

# 也可用旧包名 hub（已改名 deeplake，功能相同）
pip install hub

# 验证
python -c "import deeplake; print(deeplake.__version__)"

⚠️ 注意：Python 3.9+ 支持（v4 版本要求）。首次使用云存储功能需要在 deeplake.ai 注册获取 API Token。

核心用法

1. 快速创建数据集并写入

import deeplake

# 创建本地数据集（默认存储在当前目录）
ds = deeplake.dataset("my-first-dataset", overwrite=True)

# 定义 schema（类似定义数据表结构）
ds.create_tensor("images", htype="image", sample_compression="jpg")
ds.create_tensor("labels", htype="class_label", class_names=["cat", "dog"])

# 写入数据
with ds:
    ds.images.append(deeplake.read("cat.jpg"))
    ds.labels.append(0)  # cat=0
    ds.images.append(deeplake.read("dog.jpg"))
    ds.labels.append(1)  # dog=1

print(f"数据集大小: {len(ds)} 样本")

2. 使用云存储（S3）

import deeplake

# 连接 S3 存储桶（数据存在自己 AWS，不需要 Activeloop 服务器）
ds = deeplake.load(
    "s3://my-bucket/my-dataset",
    creds={"aws_access_key_id": "...", "aws_secret_access_key": "..."}
)

# 写入
with ds:
    ds.text.append("Hello world")
    ds.embedding.append([0.1, 0.2, 0.3])

3. 作为向量数据库（RAG 场景）

import deeplake
from deeplake.vector import VectorIndex

# 加载或创建向量索引
ds = deeplake.load("s3://my-bucket/rag-knowledge-base")

# 创建向量索引
ds.create_vector_index("content_embedding", model="sentence-transformers/all-MiniLM-L6-v2")

# 语义检索
results = ds.search(
    "content_embedding",
    query="How does PowerInfer work?",
    exec_option="python"  # 客户端执行，无需服务端
)

for result in results:
    print(result["text"][:100])

4. 与 LangChain 集成

from langchain.vectorstores import DeepLake
from langchain.embeddings import OpenAIEmbeddings

# 使用 Deep Lake 作为 LangChain 向量存储
vectorstore = DeepLake(
    dataset_path="~/deeplake/rag-app",
    embedding_function=OpenAIEmbeddings(),
    openai_api_key="sk-..."  # 或通过环境变量
)

# 添加文档
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.document_loaders import TextLoader

loader = TextLoader("my_document.txt")
docs = loader.load()
splitter = RecursiveCharacterTextSplitter(chunk_size=1000)
vectorstore.add_documents(splitter.split_documents(docs))

# 检索
results = vectorstore.similarity_search("What is txtai?")

5. 与 PyTorch 集成（训练数据流）

import deeplake
import torch
from torch.utils.data import DataLoader

# 加载公开数据集
ds = deeplake.dataset("app.activeloop.ai/activeloop/mnist")

# PyTorch 原生支持，无需手动下载和转换
dataloader = ds.dataloader().shuffle("labels").batch(32).pytorch()

for batch in dataloader:
    images = batch["images"]
    labels = batch["labels"]
    # 训练循环...

6. 数据版本控制

import deeplake

ds = deeplake.dataset("my-dataset")

# 提交当前版本（类似 git commit）
ds.commit("Added training data batch 1")

# 修改数据
with ds:
    ds.new_tensor.append(...)

# 查看历史
print(ds.history())

# 切换到指定版本
ds.checkout("version-hash-or-branch-name")

典型适用场景

场景	适用原因
RAG 应用向量存储	存 raw text + embedding 一起，支持多模态文档，云端或本地
Agent 记忆系统	结构化 + 向量双索引，支持长期记忆持久化
多模态模型训练	图片/视频/音频的惰性加载，NumPy 风格切片，不占满内存
数据版本控制	Git-like commit、branch，训练数据可回溯
企业数据合规	多云存储（自己 S3/GCS），不上传到第三方
数据协作	多数据科学家同时访问同一数据集，像 Google Docs 一样协作

坑与注意

v4 API 变化较大：旧版（Hub/deeplake v3）和 v4 API 不完全兼容，从 v3 迁移需参考官方迁移指南。
向量检索需要 TQL：复杂向量查询使用 Deep Lake 的 TQL（Tensor Query Language），语法接近 SQL 但有扩展。
数据写入事务：with ds: 块内写入，块外自动 commit，注意不要忘记 with 包裹，否则数据可能未持久化。
云存储配额：Activeloop 免费版有存储和查询配额，生产大规模数据建议连接自己的 S3/GCS/Azure。
Embedding 模型选择：向量索引默认使用 sentence-transformers/all-MiniLM-L6-v2，中文场景建议用 BAAI/bge-large-zh-v1.5。
多云认证：使用 GCS/Azure 时需要配置对应的认证凭据，首次配置较复杂，建议参考文档。
大文件存储：视频等大文件建议开启原生压缩（sample_compression），否则存储体积较大。

与同类对比

特性	Deep Lake	ChromaDB	Pinecone	Milvus	Weaviate
原始数据存储	✅ 图片/视频/音频/文本	❌ 仅 metadata	❌ 仅 metadata	❌ 仅 metadata	✅ 部分
向量检索	✅	✅	✅	✅	✅
多模态检索	✅	❌	❌	部分	✅
数据版本控制	✅	❌	❌	❌	❌
PyTorch/TF 集成	✅ 原生 dataloader	❌	❌	❌	❌
多云存储	✅ S3/GCS/Azure	❌	❌	部分	部分
Serverless	✅（v4）	❌	✅	❌	部分
开源	✅ Apache-2.0	✅	❌	✅	✅
上手难度	中	低	低	高	中

一句话总结：Deep Lake 不只是向量数据库，更是"多模态数据湖 + 向量检索 + 训练数据供给"三位一体，适合需要同时管理原始训练数据和 RAG 向量、且对数据主权有要求的企业用户。

一句话推荐结论

如果你的 AI 应用需要同时处理图片/视频等原始数据、embedding 向量和结构化元数据，不想在向量数据库、对象存储和训练 dataloader 之间来回倒腾，Deep Lake v4 是目前最值得评估的选择——一个 API 管数据，一个 dataset 搞定检索和训练。