📜 DocETL：赋能复杂文档处理流水线

DocETL 是一款用于创建和执行数据处理流水线的工具，尤其适用于复杂的文档处理任务。它提供以下功能：

1. 一个交互式 UI 演示环境，用于迭代式提示工程和流水线开发
2. 一个 Python 软件包，可用于从命令行或 Python 代码中运行生产级流水线

💡 需要帮助编写你的流水线吗？
你可以使用 Claude Code（推荐）来辅助你编写流水线——请参阅快速入门指南：https://ucbepic.github.io/docetl/quickstart-claude-code/
如果你更倾向于使用 ChatGPT 或 Claude 应用程序，请访问 docetl.org/llms.txt，那里提供了一个大型提示模板，你可以在描述任务之前直接复制粘贴。

🌟 社区项目

• 对话生成器
• 文本转语音
• YouTube 字幕主题提取

📚 教育资源

• UI/UX 思考
• 利用 Gleaning 提升输出质量
• Resolve 操作符深度解析

🚀 快速上手

使用 DocETL 主要有两种方式：

1. 🎮 DocWrangler，交互式 UI 演示环境（推荐用于开发）

DocWrangler 可帮助你逐步开发流水线：

• 实验不同的提示并实时查看结果
• 分步构建你的流水线
• 导出最终确定的流水线配置以供生产使用

DocWrangler 托管在 docetl.org/playground 上。但如果你想在本地运行演示环境，可以采取以下两种方式之一：

• 使用 Docker（推荐，快速启动）：make docker
• 手动搭建开发环境

详细说明请参阅 Playground 设置指南。

2. 📦 Python 软件包（用于生产环境）

如果你想将 DocETL 作为 Python 软件包使用：

前提条件

• Python 3.10 或更高版本
• OpenAI API 密钥

pip install docetl

在你的项目目录中创建一个 .env 文件：

OPENAI_API_KEY=your_api_key_here  # LLM 操作所需（或你选择的其他 LLM 的密钥）

⚠️ 重要提示：两个不同的 .env 文件

• 根目录下的 .env：由执行 DocETL 流水线的后端 Python 服务器使用
• website/.env.local：由 DocWrangler 的前端 TypeScript 代码使用（用于改进提示和聊天机器人等功能）

要查看如何使用 DocETL 的示例，请参阅 教程。

2. 🎮 DocWrangler 设置

要在本地运行 DocWrangler，你有两种选择：

选项 A：使用 Docker（推荐，快速启动）

让 DocWrangler 演示环境运行起来最简单的方法是：

1. 创建所需的环境文件：

在根目录下创建 .env 文件（用于执行流水线的后端 Python 服务器）：

OPENAI_API_KEY=your_api_key_here  # 用于 DocETL 流水线执行引擎
# 后端配置
BACKEND_ALLOW_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
BACKEND_HOST=localhost
BACKEND_PORT=8000
BACKEND_RELOAD=True

# 前端配置
FRONTEND_HOST=0.0.0.0
FRONTEND_PORT=3000

# Docker Compose 中的主机端口映射（若未设置，则使用 docker-compose.yml 中的默认值）
FRONTEND_DOCKER_COMPOSE_PORT=3031
BACKEND_DOCKER_COMPOSE_PORT=8081

# 支持的文本文件编码
TEXT_FILE_ENCODINGS=utf-8,latin1,cp1252,iso-8859-1

在 website 目录下创建 .env.local 文件（用于 DocWrangler UI 功能，如改进提示和聊天机器人等）：

OPENAI_API_KEY=sk-xxx  # 用于 TypeScript 功能：改进提示、聊天机器人等
OPENAI_API_BASE=https://api.openai.com/v1
MODEL_NAME=gpt-4o-mini  # UI 助手使用的模型

NEXT_PUBLIC_BACKEND_HOST=localhost
NEXT_PUBLIC_BACKEND_PORT=8000
NEXT_PUBLIC_HOSTED_DOCWRANGLER=false

2. 运行 Docker：

make docker

这将完成以下操作：

• 创建用于持久化数据的 Docker 卷
• 构建 DocETL 镜像
• 运行容器，UI 将可通过 http://localhost:3000 访问

若需清理 Docker 资源（请注意，这将删除 Docker 卷）：

make docker-clean

AWS Bedrock

该框架支持与 AWS Bedrock 的集成。要启用：

1. 配置 AWS 凭证：

aws configure

2. 测试你的 AWS 凭证：

make test-aws

3. 在启用 AWS 支持的情况下运行：

AWS_PROFILE=your-profile AWS_REGION=your-region make docker

或者使用 Docker Compose：

AWS_PROFILE=your-profile AWS_REGION=your-region docker compose --profile aws up

环境变量：

• AWS_PROFILE：你的 AWS CLI 配置文件（默认为 'default'）
• AWS_REGION：AWS 区域（默认为 'us-west-2'）

Bedrock 模型名称前会加上 bedrock_ 前缀。更多详情请参阅 liteLLM 的 文档。

选项 B：手动设置（开发模式）

如果你希望进行开发，或者不想使用 Docker，可以按以下步骤操作：

1. 克隆仓库：

git clone https://github.com/ucbepic/docetl.git
cd docetl

2. 在根目录/顶级目录下的 .env 文件中设置环境变量（用于后端 Python 服务器）：

OPENAI_API_KEY=your_api_key_here  # 用于 DocETL 流水线执行引擎
# 后端配置
BACKEND_ALLOW_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
BACKEND_HOST=localhost
BACKEND_PORT=8000
BACKEND_RELOAD=True

# 前端配置
FRONTEND_HOST=0.0.0.0
FRONTEND_PORT=3000

# Docker Compose 中的主机端口映射（若未设置，则使用 docker-compose.yml 中的默认值）
FRONTEND_DOCKER_COMPOSE_PORT=3031
BACKEND_DOCKER_COMPOSE_PORT=8081

# 支持的文本文件编码
TEXT_FILE_ENCODINGS=utf-8,latin1,cp1252,iso-8859-1

并在 website 目录下创建一个 .env.local 文件（用于 DocWrangler 的 UI 功能）：

OPENAI_API_KEY=sk-xxx  # 由 TypeScript 功能使用：改进提示、聊天机器人等。
OPENAI_API_BASE=https://api.openai.com/v1
MODEL_NAME=gpt-4o-mini  # UI 助手使用的模型。

NEXT_PUBLIC_BACKEND_HOST=localhost
NEXT_PUBLIC_BACKEND_PORT=8000
NEXT_PUBLIC_HOSTED_DOCWRANGLER=false

3. 安装依赖：

make install      # 使用 uv 安装 Python 依赖并设置 pre-commit 钩子
make install-ui   # 安装 UI 依赖

如果您更倾向于直接使用 uv 而不是 Make：

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --all-groups --all-extras

4. 启动开发服务器：

make run-ui-dev

5. 访问 http://localhost:3000/playground 即可进入交互式 UI。

🛠️ 开发环境搭建

如果您计划为 DocETL 做贡献或进行修改，可以通过运行测试套件来验证您的环境是否配置正确：

make tests-basic  # 运行基础测试套件（使用 OpenAI 时成本低于 0.01 美元）

如需详细文档和教程，请访问我们的文档。

DocETL 快速上手指南

DocETL 是一款专为复杂文档处理任务设计的数据处理流水线工具。它提供交互式 UI（DocWrangler）用于迭代开发，以及 Python 包用于生产环境部署。

1. 环境准备

在开始之前，请确保满足以下系统要求和前置依赖：

• 操作系统：支持 Docker 的环境（推荐）或 Linux/macOS/Windows。
• Python 版本：Python 3.10 或更高版本。
• API 密钥：需要 OpenAI API Key（或其他兼容 LLM 的 API Key）。
• 其他依赖：
  • 若使用 Docker 方式：需安装 Docker 和 Docker Compose。
  • 若手动开发：需安装 git 和 uv（可选，用于加速依赖安装）。

2. 安装步骤

DocETL 提供两种主要使用方式：交互式 UI (DocWrangler) 和 Python 包。推荐新手先通过 Docker 运行 UI 进行体验。

方式一：使用 Docker 运行交互式 UI（推荐）

这是最快上手的方式，无需配置复杂的本地开发环境。

1. 克隆仓库

   git clone https://github.com/ucbepic/docetl.git
   cd docetl
   

2. 配置环境变量

   在项目根目录创建 .env 文件（用于后端服务）：

   OPENAI_API_KEY=your_api_key_here
   BACKEND_ALLOW_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
   BACKEND_HOST=localhost
   BACKEND_PORT=8000
   BACKEND_RELOAD=True
   FRONTEND_HOST=0.0.0.0
   FRONTEND_PORT=3000
   FRONTEND_DOCKER_COMPOSE_PORT=3031
   BACKEND_DOCKER_COMPOSE_PORT=8081
   TEXT_FILE_ENCODINGS=utf-8,latin1,cp1252,iso-8859-1
   

   在 website 目录下创建 .env.local 文件（用于前端 UI 功能）：

   OPENAI_API_KEY=sk-xxx
   OPENAI_API_BASE=https://api.openai.com/v1
   MODEL_NAME=gpt-4o-mini
   NEXT_PUBLIC_BACKEND_HOST=localhost
   NEXT_PUBLIC_BACKEND_PORT=8000
   NEXT_PUBLIC_HOSTED_DOCWRANGLER=false
   

3. 启动服务

   make docker
   

   启动成功后，访问 http://localhost:3000 即可使用 DocWrangler playground。

方式二：作为 Python 包安装（生产环境）

如果你希望在代码中直接调用 DocETL：

1. 安装库

   pip install docetl
   

2. 配置 API Key 在项目目录下创建 .env 文件：

   OPENAI_API_KEY=your_api_key_here
   

3. 基本使用

使用交互式 UI (DocWrangler)

1. 浏览器打开 http://localhost:3000/playground。
2. 构建流水线：
   • 上传你的文档数据。
   • 添加操作算子（如提取、总结、转换等）。
   • 在右侧实时预览 Prompt 效果，调整提示词直到满意。
3. 导出配置：完成调试后，导出 pipeline 配置文件（YAML/JSON），用于后续生产环境运行。

使用 Python 代码运行流水线

安装并配置好环境后，你可以编写简单的 Python 脚本来执行处理任务：

import docetl

# 加载之前从 UI 导出的 pipeline 配置
pipeline = docetl.load_pipeline("path/to/your/pipeline.yaml")

# 执行流水线
results = pipeline.run()

# 查看结果
for result in results:
    print(result)

提示：如果你不熟悉如何编写 Pipeline 配置，可以使用 Claude Code 或参考 docetl.org/llms.txt 中的提示词模板，让 AI 辅助生成初始配置。