lamindb

LaminDB

概述

LaminDB 是一个开源、原生支持血缘追踪的生物学湖仓。它使数据集和模型可查询、可追溯、可验证、可复现，并符合 FAIR（可发现、可访问、可互操作、可复用）原则，同时以开放格式将数据存储在本地文件系统、S3、GCS、Hugging Face、SQLite 和 Postgres 中。

核心价值主张：

• 可查询性：搜索和筛选工件、记录、运行、特征、架构和集合
• 可追溯性：追踪笔记本、脚本、函数和管道的输入、输出、参数、源代码及环境
• 数据验证：使用架构整理 DataFrame、AnnData、SpatialData、TileDB-SOMA、Parquet、Zarr 及其他生物学格式的数据
• 符合 FAIR 原则：借助 Bionty 支持的本体和自定义注册表规范化注释
• 变更管理：通过项目、分支、空间、集合以及保存的笔记或计划来组织工作

何时使用此技能

在以下情况下使用此技能：

• 管理生物学数据集：scRNA-seq、bulk RNA-seq、空间转录组学、流式细胞术、多模态数据、EHR 数据
• 追踪计算工作流：笔记本、脚本、函数、shell 脚本和管道执行（Nextflow、Snakemake、Redun）
• 整理和验证数据：架构验证、标准化、基于本体的注释
• 使用生物学本体：基因、蛋白质、细胞类型、组织、疾病、通路（通过 Bionty）
• 构建数据湖仓：跨多个数据集的统一查询接口
• 确保可复现性：自动版本控制、血缘追踪、环境捕获
• 集成 ML 管道：连接 Weights & Biases、MLflow、Hugging Face、Lightning、scVI-tools
• 部署数据基础设施：设置本地或基于云的数据管理系统
• 协作处理数据集：共享经过整理和注释且具有标准化元数据的数据

核心功能

LaminDB 提供六个相互关联的功能领域，参考资料文件夹中对每个领域都有详细说明。

1. 核心概念与数据血缘

核心实体：

• 工件：带版本的数据集（DataFrame、AnnData、Parquet、Zarr 等）
• 记录与 ULabels：实验实体、类型化记录和简单标签
• 集合：带版本且不可变的工件集合
• 运行与转换：计算血缘追踪（哪些代码生成了哪些数据）
• 特征：用于注释和查询的类型化元数据字段
• 项目、分支与空间：项目分组、变更管理和访问边界

关键工作流：

• 从文件或 Python 对象创建工件并为其添加版本
• 使用 ln.track() 和 ln.finish() 追踪笔记本／脚本的执行
• 使用 @ln.flow() 和 @ln.step() 追踪函数工作流
• 使用记录、ulabels、项目和类型化特征为工件添加注释
• 使用 artifact.view_lineage() 可视化数据血缘图
• 按来源信息查询（查找特定代码／输入所产生的所有输出）

参考资料： references/core-concepts.md - 阅读此文档，了解工件、记录、运行、转换、特征、版本控制和血缘追踪的详细信息。

2. 数据管理与查询

查询功能：

• 通过自动补全浏览和查找注册表
• 使用 get()、one()、one_or_none() 获取单条记录
• 使用比较运算符进行筛选（__gt、__lte、__contains、__startswith）
• 基于特征查询，包括使用 Feature 对象进行表达式式查询
• 使用双下划线语法跨注册表遍历
• 跨注册表进行全文搜索
• 使用 ln.Q 对象进行高级逻辑查询（AND、OR、NOT）
• 流式处理大型数据集，无需将其加载到内存中

关键工作流：

• 使用筛选条件和排序浏览制品
• 按特征、创建日期、创建者、大小等条件查询
• 通过分块或数组切片流式读取大型文件
• 使用分层键组织数据
• 将制品分组到集合中

参考： references/data-management.md — 阅读此文档，了解全面的查询模式、筛选示例、流式处理策略和数据组织最佳实践。

3. 注释与验证

整理流程：

1. 验证： 确认数据集符合预期的架构
2. 标准化： 修正拼写错误，将同义词映射到规范术语
3. 注释： 将数据集关联到元数据实体，以便进行查询

架构类型：

• 灵活架构： 仅验证已知列，允许额外元数据
• 最小必需架构： 指定必要列，允许其他列
• 严格架构： 完全控制结构和值

支持的数据类型：

• DataFrame（Parquet、CSV）
• AnnData（单细胞基因组学）
• MuData（多模态）
• SpatialData（空间转录组学）
• TileDB-SOMA（可扩展数组）

关键工作流：

• 定义特征和架构，以验证数据
• 使用 DataFrameCurator、AnnDataCurator、SpatialDataCurator 或 TiledbsomaExperimentCurator 进行验证
• 使用 .cat.standardize() 标准化取值
• 使用 .cat.add_ontology() 映射到本体
• 保存关联了架构的整理后制品
• 按特征查询经过验证的数据集

参考： references/annotation-validation.md — 阅读此文档，了解详细的整理工作流、架构设计模式、验证错误处理方式和最佳实践。

4. 生物本体

可用本体（通过 Bionty）：

• 基因（Ensembl）、蛋白质（UniProt）
• 细胞类型（CL）、细胞系（CLO）
• 组织（Uberon）、疾病（Mondo、DOID）
• 表型（HPO）、通路（GO）
• 实验因素（EFO）、发育阶段
• 生物体（NCBItaxon）、药物（DrugBank）

关键工作流：

• 使用 bt.CellType.import_source() 导入公共本体
• 使用关键词或精确匹配搜索本体
• 使用同义词映射标准化术语
• 浏览层级关系（父项、子项、祖先项）
• 根据本体术语验证数据
• 使用本体记录注释数据集
• 创建自定义术语和层级
• 处理多生物体环境（人、小鼠等）

参考： references/ontologies.md — 阅读此文档，了解全面的本体操作、标准化策略、层级导航和注释工作流。

5. 集成

工作流管理器：

• Nextflow：跟踪流水线进程和输出
• Snakemake：集成到 Snakemake 规则中
• Redun：结合 Redun 任务跟踪
• Lightning：持久化检查点和训练元数据

MLOps 平台：

• Weights & Biases：关联实验与数据制品
• MLflow：跟踪模型和实验
• Hugging Face：跟踪模型微调
• scVI-tools：单细胞分析工作流

存储系统：

• 本地文件系统、AWS S3、Google Cloud Storage
• 兼容 S3 的存储（MinIO、Cloudflare R2）
• HTTP/HTTPS 端点（只读）
• HuggingFace 数据集

数组存储：

• TileDB-SOMA（支持 cellxgene）
• 使用 DuckDB 对 Parquet 文件进行 SQL 查询

可视化：

• 使用 Vitessce 进行交互式空间/单细胞可视化

版本控制：

• 集成 Git 以跟踪源代码

参考： references/integrations.md - 阅读此文档，了解第三方系统的集成模式、代码示例和故障排查方法。

6. 设置和部署

安装：

• 当前稳定基线：lamindb==2.5.1（于 2026-06-01 发布；Python >=3.10、<=3.14）
• 基础安装：uv pip install 'lamindb==2.5.1'
• 安装额外组件：uv pip install 'lamindb[gcp,zarr-v2,fcs]==2.5.1'
• 仅安装最小命名空间：uv pip install 'lamindb-core==2.5.1'
• Bionty 模块：包含在 LaminDB 文档中，可通过 uv pip install 'bionty==2.4.0' 安装
• 可选模块：湿实验室或临床架构模块应固定为经过审核的版本，而不是安装浮动的最新版本

实例类型：

• 本地 SQLite（开发）
• 云存储 + SQLite（小型团队）
• 云存储 + PostgreSQL（生产环境）

存储选项：

• 本地文件系统
• 可配置区域和权限的 AWS S3
• Google Cloud Storage
• 兼容 S3 的端点（MinIO、Cloudflare R2）

配置：

• 云文件缓存管理
• 多用户系统配置
• Git 仓库同步
• 用于凭据和连接 URL 的命名环境变量

部署模式：

• 从本地开发迁移到云端生产环境
• 多区域部署
• 共享存储搭配个人实例

参考： references/setup-deployment.md - 阅读此文档，了解详细的安装、配置、存储设置、数据库管理、安全最佳实践和故障排查方法。

安全与防护默认设置

在协助设置 LaminDB 或进行集成时：

• 切勿显示、记录或传输实际的 API 密钥、云凭据、数据库密码或包含机密信息的完整连接字符串。
• 优先使用 IAM 角色、工作负载身份、密钥管理器或命名环境变量，例如 LAMIN_DB_URL、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 GOOGLE_APPLICATION_CREDENTIALS；仅检查指定变量是否存在，不要读取其值。
• 在保存来自 REST API、外部数据库或用户提供文件的内容之前，使用明确的架构或数据管理员对其进行验证和清理。
• 为确保安装可复现，请固定软件包版本或使用锁文件。仅当用户明确要求使用上游最新版本时，才可使用浮动安装。

常见用例工作流

用例 1：使用本体验证进行单细胞 RNA-seq 分析

import lamindb as ln
import bionty as bt
import anndata as ad

# Start tracking a notebook/script run
ln.track(params={"analysis": "scRNA-seq QC and annotation"})

# Import cell type ontology
bt.CellType.import_source()

# Load data
adata = ad.read_h5ad("raw_counts.h5ad")

# Validate and standardize cell types
adata.obs["cell_type"] = bt.CellType.standardize(adata.obs["cell_type"])

# Curate with schema
curator = ln.curators.AnnDataCurator(adata, schema)
curator.validate()
artifact = curator.save_artifact(key="scrna/validated.h5ad")

# Link ontology-backed annotations for queryability
cell_types = bt.CellType.from_values(adata.obs["cell_type"])
artifact.cell_types.add(*cell_types)

ln.finish()

用例 2：构建可查询的数据湖仓

import lamindb as ln

# Register multiple experiments
for i, file in enumerate(data_files):
    artifact = ln.Artifact.from_anndata(
        ad.read_h5ad(file),
        key=f"scrna/batch_{i}.h5ad",
        description=f"scRNA-seq batch {i}"
    ).save()

    # Annotate with features
    artifact.features.set_values({
        "batch": i,
        "tissue": tissues[i],
        "condition": conditions[i]
    })

# Query across all experiments by annotated features
immune_datasets = ln.Artifact.filter(
    key__startswith="scrna/",
    tissue="PBMC",
    condition="treated"
).to_dataframe()

# Load specific datasets
for artifact in immune_datasets:
    adata = artifact.load()
    # Analyze

用例 3：集成 W&B 的 ML 流水线

import lamindb as ln
import wandb

# Initialize both systems
wandb.init(project="drug-response", name="exp-42")
ln.track(params={"model": "random_forest", "n_estimators": 100})

# Load training data from LaminDB
train_artifact = ln.Artifact.get(key="datasets/train.parquet")
train_data = train_artifact.load()

# Train model
model = train_model(train_data)

# Log to W&B
wandb.log({"accuracy": 0.95})

# Save model in LaminDB with W&B linkage
import joblib
joblib.dump(model, "model.pkl")
model_artifact = ln.Artifact("model.pkl", key="models/exp-42.pkl").save()
model_artifact.features.set_values({"wandb_run_id": wandb.run.id})

ln.finish()
wandb.finish()

用例 4：Nextflow 流水线集成

# In Nextflow process script
import lamindb as ln

ln.track()

# Load input artifact
input_artifact = ln.Artifact.get(key="raw/batch_${batch_id}.fastq.gz")
input_path = input_artifact.cache()

# Process (alignment, quantification, etc.)
# ... Nextflow process logic ...

# Save output
output_artifact = ln.Artifact(
    "counts.csv",
    key="processed/batch_${batch_id}_counts.csv"
).save()

ln.finish()

对于原生 Nextflow 项目，优先使用 nf-lamin 插件和当前的 nextflow.config 模式（如果可用）；对于小型或自定义流水线步骤，则使用内联 Python 跟踪。

入门清单

要有效地开始使用 LaminDB：

1. 安装与设置（references/setup-deployment.md）

   • 安装固定版本的 LaminDB 和所需的额外组件
   • 使用 lamin login 进行身份验证
   • 使用 lamin init --storage ... 初始化实例

2. 了解核心概念（references/core-concepts.md）

   • 了解 Artifacts、Records、Runs 和 Transforms
   • 练习创建和检索 artifacts
   • 在工作流中实现 ln.track()/ln.finish() 或 @ln.flow()/@ln.step()

3. 掌握查询（references/data-management.md）

   • 练习筛选和搜索注册表
   • 学习基于特征的查询和表达式风格的筛选器
   • 尝试流式处理大型文件

4. 设置验证（references/annotation-validation.md）

   • 定义与研究领域相关的特征
   • 为数据类型创建架构
   • 练习整理工作流

5. 集成本体（references/ontologies.md）

   • 导入相关的生物本体（基因、细胞类型等）
   • 验证现有注释
   • 使用本体术语规范化元数据

6. 连接工具（references/integrations.md）

   • 与现有工作流管理器集成
   • 连接 ML 平台以跟踪实验
   • 配置云存储和计算资源

核心原则

使用 LaminDB 时请遵循以下原则：

1. 跟踪所有内容：在每次分析开始时使用 ln.track()，自动捕获数据血缘

2. 尽早验证：定义架构并在深入分析前验证数据

3. 使用本体：利用公开的生物本体规范注释

4. 使用键组织数据：按层次结构组织 artifact 键（例如，project/experiment/batch/file.h5ad）

5. 优先查询元数据：先筛选和搜索，再加载大型文件

6. 创建版本，而非副本：使用内置版本控制，而不是为修改创建新键

7. 使用特征进行注释：定义类型化特征，并使用 artifact.features.set_values() 设置可查询的元数据

8. 详尽记录：为 artifacts、架构和 transforms 添加描述

9. 利用数据血缘：使用 view_lineage() 了解数据来源

10. 先本地开发，再扩展到云端：使用 SQLite 在本地开发，使用 PostgreSQL 部署到云端

参考文件

此技能包含按功能整理的全面参考文档：

• references/core-concepts.md - Artifacts、records、runs、transforms、features、版本控制、数据血缘
• references/data-management.md - 查询、筛选、搜索、流式处理、数据组织
• references/annotation-validation.md - 架构设计、整理工作流、验证策略
• references/ontologies.md - 生物本体管理、规范化、层次结构
• references/integrations.md - 工作流管理器、MLOps 平台、存储系统、工具
• references/setup-deployment.md - 安装、配置、部署、故障排除

根据当前任务所需的具体 LaminDB 功能，阅读相关参考文件。

其他资源

• 官方文档：https://docs.lamin.ai
• API 参考：https://docs.lamin.ai/api
• GitHub 仓库：https://github.com/laminlabs/lamindb
• 教程：https://docs.lamin.ai/tutorial
• 常见问题：https://docs.lamin.ai/faq

Agent 操作流程

1. 检查环境。 确认 Python 环境和库版本（python -c "import pkg; print(pkg.__version__)"），并检查数据的形状、类型和缺失值。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。对于任何会改变结果的值，应先询问，不要猜测。
3. 先运行小规模版本。 先在样本或单个折上运行，并检查运行时间和内存。
4. 根据上述说明和参考资料执行完整任务。
5. 验证结果。 使用留出数据、固定随机种子和适当的指标；检查是否存在数据泄漏；报告不确定性（置信区间、不同种子下的标准差）。
6. 汇报。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
内存不足或执行非常缓慢	使用子样本、分块或惰性计算，或缩小模型规模，并告知用户做了哪些调整。
已安装版本中缺少这些说明里的函数、标志或端点	查阅已安装版本自己的文档（help()、--help、官方文档），调整用法，并告知用户。切勿编造 API。
必需的输入、标识符或参数存在歧义	询问用户，或在运行前明确说明假设。

诚信规则

• 切勿编造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，应坦率说明。
• 切勿报告本次会话中未计算的指标；应展示生成每个数值的代码路径。
• 将此处与版本相关的细节视为可能已过时：请根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须事先征得同意。

相关技能

• qdrant-vector-search：用于 RAG 和语义搜索的高性能向量相似度搜索引擎。