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 等）
- 记录与 ULabel：实验实体、类型化记录和简单标签
- 集合：版本化、不可变的工件集
- 运行与转换：计算谱系追踪（什么代码产生了什么数据）
- 特征：用于标注和查询的类型化元数据字段
- 项目、分支与空间：项目分组、变更管理和访问边界
关键工作流：
- 从文件或 Python 对象创建并版本控制工件
- 使用
ln.track()和ln.finish()追踪笔记本/脚本执行 - 使用
@ln.flow()和@ln.step()追踪函数工作流 - 使用记录、ulabel、项目和类型化特征标注工件
- 使用
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. 标注与验证
整理过程：
- 验证：确认数据集符合预期的模式
- 标准化：修复拼写错误，将同义词映射到标准术语
- 标注：将数据集链接到元数据实体以实现可查询性
模式类型：
- 灵活模式：仅验证已知列，允许额外的元数据
- 最小必需模式：指定关键列，允许额外列
- 严格模式：完全控制结构和值
支持的数据类型：
- 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
# 开始追踪笔记本/脚本运行
ln.track(params={"analysis": "scRNA-seq QC and annotation"})
# 导入细胞类型本体
bt.CellType.import_source()
# 加载数据
adata = ad.read_h5ad("raw_counts.h5ad")
# 验证并标准化细胞类型
adata.obs["cell_type"] = bt.CellType.standardize(adata.obs["cell_type"])
# 使用模式进行整理
curator = ln.curators.AnnDataCurator(adata, schema)
curator.validate()
artifact = curator.save_artifact(key="scrna/validated.h5ad")
# 链接本体支持的标注以实现可查询性
cell_types = bt.CellType.from_values(adata.obs["cell_type"])
artifact.cell_types.add(*cell_types)
ln.finish()
用例 2：构建可查询的数据湖仓
import lamindb as ln
# 注册多个实验
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()
# 使用特征进行标注
artifact.features.set_values({
"batch": i,
"tissue": tissues[i],
"condition": conditions[i]
})
# 根据标注的特征查询所有实验
immune_datasets = ln.Artifact.filter(
key__startswith="scrna/",
tissue="PBMC",
condition="treated"
).to_dataframe()
# 加载特定数据集
for artifact in immune_datasets:
adata = artifact.load()
# 分析
用例 3：集成 W&B 的 ML 管道
import lamindb as ln
import wandb
# 初始化两个系统
wandb.init(project="drug-response", name="exp-42")
ln.track(params={"model": "random_forest", "n_estimators": 100})
# 从 LaminDB 加载训练数据
train_artifact = ln.Artifact.get(key="datasets/train.parquet")
train_data = train_artifact.load()
# 训练模型
model = train_model(train_data)
# 记录到 W&B
wandb.log({"accuracy": 0.95})
# 在 LaminDB 中保存模型并与 W&B 关联
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 管道集成
# 在 Nextflow 进程脚本中
import lamindb as ln
ln.track()
# 加载输入工件
input_artifact = ln.Artifact.get(key="raw/batch_${batch_id}.fastq.gz")
input_path = input_artifact.cache()
# 处理（比对、定量等）
# ... Nextflow 进程逻辑 ...
# 保存输出
output_artifact = ln.Artifact(
"counts.csv",
key="processed/batch_${batch_id}_counts.csv"
).save()
ln.finish()
对于原生 Nextflow 项目，如果可用，优先使用 nf-lamin 插件和当前的 nextflow.config 模式；对于小型或自定义管道步骤，可以使用内联 Python 追踪。
入门检查清单
要开始有效使用 LaminDB：
-
安装与设置（
references/setup-deployment.md）- 安装固定的 LaminDB 和所需的额外功能
- 使用
lamin login进行身份验证 - 使用
lamin init --storage ...初始化实例
-
学习核心概念（
references/core-concepts.md）- 理解工件、记录、运行、转换
- 练习创建和检索工件
- 在工作流中实现
ln.track()/ln.finish()或@ln.flow()/@ln.step()
-
掌握查询（
references/data-management.md）- 练习过滤和搜索注册表
- 学习基于特征的查询和表达式风格过滤器
- 尝试流式传输大文件
-
设置验证（
references/annotation-validation.md）- 定义与研究领域相关的特征
- 为数据类型创建模式
- 练习整理工作流
-
集成本体（
references/ontologies.md）- 导入相关的生物本体（基因、细胞类型等）
- 验证现有标注
- 使用本体术语标准化元数据
-
连接工具（
references/integrations.md）- 与现有的工作流管理器集成
- 连接 ML 平台以进行实验追踪
- 配置云存储和计算
关键原则
使用 LaminDB 时遵循以下原则：
-
追踪一切：在每个分析开始时使用
ln.track()以自动捕获谱系 -
及早验证：在深入分析之前定义模式并验证数据
-
使用本体：利用公共生物本体进行标准化标注
...
[为翻译而截断]