LOTUS：快速、简单且精准的LLM驱动数据处理

LOTUS是一个框架，使您能够轻松地使用LLM处理数据集，包括非结构化和结构化数据。它提供了一个直观的类似Pandas的API，提供了用于将程序优化至最高1000倍加速的算法，并通过与高质量参考算法相关的准确性保证，使基于LLM的数据处理变得稳健可靠。

LOTUS代表LLMs Over Text, Unstructured and Structured Data，它引入了语义运算符。语义运算符将关系运算符的核心理念——专为声明式和稳健的_结构化数据_处理而设计——扩展到使用AI进行的_非结构化数据_处理。语义运算符表达力强大，可让您轻松实现所有数据密集型AI程序，从简单的RAG、文档提取、图像分类、LLM评判评估、非结构化数据分析，到复杂的研究型综合等。

如遇问题或有功能需求，请提交问题，我们将尽快处理。如需分享反馈或您正在进行的应用，请在我们的社区Discord上留言，或发送邮件至lianapat@stanford.edu。

安装

使用uv（推荐）

获取最新稳定版：

# 如果尚未安装uv，请先安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建新项目或进入现有项目
uv add lotus-ai

获取最新功能版：

uv add git+https://github.com/lotus-data/lotus.git@main

使用pip

获取最新稳定版：

conda create -n lotus python=3.10 -y
conda activate lotus
pip install lotus-ai

若要获取最新功能版，也可按以下方式安装：

conda create -n lotus python=3.10 -y
conda activate lotus
pip install git+https://github.com/lotus-data/lotus.git@main

在Mac上运行

如果您在Mac上使用pip，请通过conda安装Faiss：

仅CPU版本

conda install -c pytorch faiss-cpu=1.8.0

GPU(+CPU)版本

conda install -c pytorch -c nvidia faiss-gpu=1.8.0

如果您使用uv，faiss-cpu依赖项将自动处理。

更多详情请参阅通过Conda安装FAISS。

快速入门

如果您已经熟悉Pandas，那么上手将会非常容易！下面我们提供一个使用sem_filter的简单示例。与所有语义运算符一样，它由一个langex参数指定，该参数以方括号中的一个或多个列名进行参数化——此处为{title}。sem_filter的langex是一个NL谓词，即可以评估为真/假值的自然语言表达式。

import pandas as pd
import lotus
from lotus.models import LM

# 配置LM — 运行前请导出您的API密钥（例如OPENAI_API_KEY）
lm = LM(model="gpt-4.1-nano")
lotus.settings.configure(lm=lm)

# 来自开源项目的GitHub风格议题标题样本
issues = pd.DataFrame({
    "title": [
        "修复README中的拼写错误",
        "为仪表板添加暗模式支持",
        "重构整个认证系统以使用OAuth2",
        "更新LICENSE中的版权年份",
        "在微服务间实现分布式事务支持",
        "更改设置页面上的按钮颜色",
        "将数据库从Postgres 13无缝迁移到16",
        "在错误信息中添加缺失的逗号",
        "构建自定义查询计划器以替代第三方依赖",
        "升级lodash以修复已知CVE漏洞",
        "支持多区域主动-主动复制",
        "移除utils.py中未使用的导入"
    ]
})

# 使用sem_filter查找适合首次贡献者的议题
good_first_issues = issues.sem_filter(
    "该{title}描述了一项小型、独立的任务，新的开源贡献者无需深入了解代码库即可完成"
)

print("适合新贡献者的优质议题：\n")
print(good_first_issues.to_string(index=False))

# 如需打印总LLM用量，请取消注释
# lm.print_total_usage()

教程

以下是几个在 Google Colab 中的简短教程，帮助您快速上手。我们建议从 [1] 语义算子与 LOTUS 简介 开始，它将为您提供有用功能的概览，助您顺利入门。

核心概念：语义算子模型

LOTUS 引入了语义算子编程模型。语义算子是对一个或多个数据集进行声明式转换的操作，由自然语言表达式参数化，并可通过多种基于 AI 的算法实现。语义算子无缝扩展了关系模型，可在包含传统结构化数据以及自由文本等非结构化字段的表上运行。这些基于语言的模块化算子使您可以使用高级逻辑编写基于 AI 的管道，而将优化工作交由查询引擎完成。每个算子都可以通过多种方式实现和优化，从而为执行计划提供了丰富的可能性，类似于关系算子。要深入了解语义算子模型，请阅读完整的研究论文。

LOTUS 提供了一系列类似 Pandas API 的语义算子，其中部分如下所述。如需了解更多关于 LOTUS 中提供的语义算子的信息，请查阅完整的文档、运行Colab 教程，或参考这些示例。

语义算子为基于 LLM 的原语提供统一的 API……

算子	描述
sem_map	使用自然语言投影映射每条记录
sem_filter	保留符合自然语言谓词的记录
sem_extract	从每行提取一个或多个属性
sem_agg	对所有记录进行聚合（例如用于汇总）
sem_topk	按照某种自然语言排序标准对记录排序
sem_join	根据自然语言谓词连接两个数据集

……以及基于嵌入的原语：

算子	描述
sem_sim_join	根据语义相似度连接两个 DataFrame
sem_search	在文本列中执行语义搜索

支持的模型

LOTUS 中有 3 类主要模型：

• LM：语言模型类。
  • LM 类构建于 LiteLLM 库之上，支持任何被 LiteLLM 支持的模型。请参阅此页面，了解如何使用 OpenAI、Ollama 和 vLLM 等模型的示例。任何被 LiteLLM 支持的提供商都应能正常工作。更多信息请参阅 litellm 的文档。
• RM：检索模型类。
  • 可以使用 SentenceTransformers 中的任何模型与 SentenceTransformersRM 类一起使用，只需将模型名称传递给 model 参数即可（参见此处的示例）。此外，LiteLLMRM 也可与任何被 LiteLLM 支持的模型一起使用（参见此处的示例）。
• Reranker：重排序模型类。
  • 可以使用 SentenceTransformers 中的任何 CrossEncoder 与 CrossEncoderReranker 类一起使用，只需将模型名称传递给 model 参数即可（参见此处的示例）。

贡献

我们欢迎社区的贡献！无论您是报告 bug、提出功能建议，还是贡献代码，我们都准备了全面的模板和指南来帮助您开始。

入门指南

在开始贡献之前，请：

1. 阅读我们的贡献指南 - 为贡献者提供的全面指南
2. 检查现有问题 - 通过搜索现有问题和拉取请求避免重复
3. 加入我们的社区 - 通过Discord与我们联系

社区

• Discord: 加入我们的社区
• 电子邮件: lianapat@stanford.edu
• 讨论: GitHub 讨论

我们非常期待看到您使用 LOTUS 构建的内容！🚀 如果您希望被列入用户名单并展示您的项目，请联系 lianapat@stanford.edu。

参考文献

如需了解 LOTUS 的最新动态，请在 X 平台上关注 [@lianapatel_]。

如果您认为 LOTUS 或语义算子很有用，我们诚挚地希望您能按以下方式引用本工作：

@article{patel2025semanticoptimization,
    title = {语义算子及其优化：在 LOTUS 中实现具有准确率保证的基于大语言模型的数据处理},
    author = {Patel, Liana and Jha, Siddharth and Pan, Melissa and Gupta, Harshit and Asawa, Parth and Guestrin, Carlos and Zaharia, Matei},
    year = {2025},
    journal = {Proc. VLDB Endow.},
    url = {https://doi.org/10.14778/3749646.3749685},
}
@article{patel2024semanticoperators,
      title={语义算子：面向文本数据的丰富、基于 AI 的分析的声明式模型},
      author={Liana Patel 和 Siddharth Jha、Parth Asawa、Melissa Pan、Carlos Guestrin 以及 Matei Zaharia},
      year={2024},
      eprint={2407.11418},
      url={https://arxiv.org/abs/2407.11418},
}

LOTUS 快速上手指南

LOTUS 是一个基于大语言模型（LLM）的数据处理框架，专为处理非结构化和结构化数据设计。它提供类似 Pandas 的直观 API，支持通过自然语言表达式（Semantic Operators）对数据进行过滤、映射、提取和聚合等操作，并内置优化算法以提升执行效率。

环境准备

• 操作系统：Linux、macOS 或 Windows
• Python 版本：推荐 Python 3.10
• 前置依赖：
  • conda（推荐用于管理环境和安装 Faiss）
  • LLM API Key（如 OpenAI API Key，需设置为环境变量 OPENAI_API_KEY）
  • Mac 用户若使用 pip 安装，需手动安装 Faiss（见安装步骤）

注意：国内开发者如遇网络问题，可配置 Conda 或 Pip 国内镜像源加速下载。

• Conda 清华源：https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
• Pip 清华源：https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

方式一：使用 uv（推荐）

uv 是更快的 Python 包管理工具，能自动处理依赖（包括 Faiss）。

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建项目并安装 lotus-ai
uv add lotus-ai

如需体验最新功能（开发版）：

uv add git+https://github.com/lotus-data/lotus.git@main

方式二：使用 pip + conda

# 创建并激活虚拟环境
conda create -n lotus python=3.10 -y
conda activate lotus

# 安装 lotus-ai
pip install lotus-ai

Mac 用户特别步骤： 若使用 pip 安装，需单独通过 conda 安装 Faiss：

CPU 版本：

conda install -c pytorch faiss-cpu=1.8.0

GPU 版本：

conda install -c pytorch -c nvidia faiss-gpu=1.8.0

基本使用

LOTUS 的核心是“语义算子”（Semantic Operators），允许你用自然语言描述数据处理逻辑。以下示例演示如何使用 sem_filter 筛选适合新手的 GitHub Issue。

import pandas as pd
import lotus
from lotus.models import LM

# 1. 配置大模型 (确保已导出 OPENAI_API_KEY)
lm = LM(model="gpt-4.1-nano")
lotus.settings.configure(lm=lm)

# 2. 准备数据 (模拟 GitHub Issue 标题)
issues = pd.DataFrame({
    "title": [
        "Fix typo in README",
        "Add dark mode support to dashboard",
        "Refactor entire auth system to use OAuth2",
        "Update copyright year in LICENSE",
        "Implement distributed transaction support across microservices",
        "Change button color on settings page",
        "Migrate database from Postgres 13 to 16 with zero downtime",
        "Add missing comma in error message",
        "Build custom query planner to replace third-party dependency",
        "Bump lodash to fix known CVE",
        "Support multi-region active-active replication",
        "Remove unused import in utils.py",
    ]
})

# 3. 使用 sem_filter 进行语义过滤
# 语法：df.sem_filter("自然语言描述 {列名}")
good_first_issues = issues.sem_filter(
    "The {title} describes a small, self-contained task that a new open source contributor could tackle without deep knowledge of the codebase"
)

# 4. 查看结果
print("Good first issues for new contributors:\n")
print(good_first_issues.to_string(index=False))

核心语义算子速查

算子	功能描述
sem_map	使用自然语言对每条记录进行转换/映射
sem_filter	保留符合自然语言谓词的记录
sem_extract	从每行提取特定属性
sem_agg	对所有记录进行聚合（如总结）
sem_topk	按自然语言标准排序并取前 K 个
sem_join	基于自然语言条件连接两个数据集
sem_sim_join	基于语义相似度连接两个 DataFrame
sem_search	在文本列上执行语义搜索

更多高级用法请参考官方 Colab 教程或文档。