Unstract Executor 迁移本地开发完全指南:Pluggable Executor 系统 v2 的搭建、运行与排查
Unstract Executor 迁移本地开发完全指南:Pluggable Executor 系统 v2 的搭建、运行与排查
本篇指南基于仓库中的 docs/local-dev-setup-executor-migration.md(分支 feat/execution-backend,2026-02-19)编写,完整覆盖 Unstract 执行器迁移(Executor Migration)后的本地开发与联调:迁移后的架构形态、服务依赖图、Docker Compose 分步启动、环境变量配置、executor worker 的三种启动方式、端口与 Health Check 参考、故障排查手册,以及五阶段验证清单。读完本文后,你能够独立在本地拉起完整的 Unstract 执行栈、让 execute_extraction 任务在 executor worker 上被正确路由和执行,并能用仓库源码级别的证据(workers/worker.py、workers/executor/tasks.py、unstract/sdk1/src/unstract/sdk1/execution/orchestrator.py 等)理解每一步背后的调用链。
1. 迁移后的架构总览
迁移后的调用链分为两条入口路径,最终汇聚到同一个 Celery 任务 execute_extraction:
┌──────────────────────────────────────────────────────────────┐
│ CALLERS │
│ │
│ Workflow Path: │
│ process_file_batch → structure_tool_task │
│ → ExecutionDispatcher.dispatch() [Celery] │
│ → AsyncResult.get() │
│ │
│ Prompt Studio IDE: │
│ Django View → PromptStudioHelper │
│ → ExecutionDispatcher.dispatch() [Celery] │
│ → AsyncResult.get() │
└───────────────────────┬──────────────────────────────────────┘
│ Celery task: execute_extraction
▼
┌──────────────────────────────────────────────────────────────┐
│ EXECUTOR WORKER (dedicated, queue: "executor") │
│ │
│ execute_extraction task │
│ → ExecutionOrchestrator → ExecutorRegistry → LegacyExecutor │
│ → Returns ExecutionResult via Celery result backend │
└──────────────────────────────────────────────────────────────┘
迁移改变了什么:
prompt-serviceFlask 应用被 替换 为 executor worker(Celery);- Structure tool 的 Docker 容器被 替换 为
structure_tool_task(file_processing worker 中的 Celery 任务,对应 workers/file_processing/structure_tool_task.py); PromptToolSDK 的 HTTP 客户端被 替换 为ExecutionDispatcher(Celery 分发,位于 unstract/sdk1/src/unstract/sdk1/execution/dispatcher.py);- 没有数据库 schema 变更 —— 不需要新的 Django 迁移。
保持不变的部分:
platform-service(端口 3001)—— 仍然提供工具元数据;runner(端口 5002)—— Classifier、Text Extractor、Translate 等工具仍依赖它;x2text-service(端口 3004)—— 文本抽取服务;- 所有 adapter SDK(LLM、Embedding、VectorDB、X2Text)—— LegacyExecutor 通过 ExecutorToolShim(workers/executor/executor_tool_shim.py)使用它们;
- 前端无任何改动(REST API 响应保持一致)。
从源码看,execute_extraction 是整条链路的单点入口:workers/executor/tasks.py 中的任务将传入的 execution_context_dict 反序列化为 ExecutionContext,交给 ExecutionOrchestrator 执行,再把 ExecutionResult 序列化返回;而 ExecutorRegistry 的注册则依赖 workers/executor/worker.py 中的 import executor.executors 在导入期触发 @ExecutorRegistry.register。
2. 前置条件
2.1 系统要求
| 要求 | 最低版本 | 说明 |
|---|---|---|
| Docker + Docker Compose | v2.20+ | 用 docker compose version 验证 |
| Python | 3.11+ | 系统 Python 或 pyenv |
| uv | 最新版 | pip install uv,或使用仓库本地二进制 backend/venv/bin/uv |
| Git | 2.30+ | 位于 feat/execution-backend 分支 |
| 可用内存 | 8 GB+ | 多个服务并发运行 |
| 可用磁盘 | 10 GB+ | Docker 镜像 + 数据卷 |
2.2 确认分支
cd <repo-root>
git branch --show-current
# 预期输出: feat/execution-backend
2.3 需要构建的镜像
# 构建全部镜像(从 docker/ 目录)
cd docker
docker compose -f docker-compose.build.yaml build
# 或只构建关键镜像:
docker compose -f docker-compose.build.yaml build backend
docker compose -f docker-compose.build.yaml build platform-service
docker compose -f docker-compose.build.yaml build worker-unified # 含 executor 的 V2 worker
docker compose -f docker-compose.build.yaml build runner
docker compose -f docker-compose.build.yaml build frontend
提示: 更快速的开发构建可在 docker-compose.build.yaml 的 args 中设置
MINIMAL_BUILD=1。
3. 服务依赖图
3.1 基础基础设施(任何功能运行的前提)
| 服务 | 容器 | 端口 | 用途 |
|---|---|---|---|
| PostgreSQL (pgvector) | unstract-db |
5432 | 主数据库 |
| Redis | unstract-redis |
6379 | 缓存 + 队列 |
| RabbitMQ | unstract-rabbitmq |
5672 (AMQP)、15672 (管理 UI) | Celery 消息 broker |
| MinIO | unstract-minio |
9000 (S3 API)、9001 (Console) | 对象存储 |
| Traefik | unstract-proxy |
80、8080 (Dashboard) | 反向代理 |
3.2 应用服务
| 服务 | 容器 | 端口 | 用途 |
|---|---|---|---|
| Backend (Django) | unstract-backend |
8000 | API、认证、DB 迁移 |
| Platform Service | unstract-platform-service |
3001 | 工具元数据、adapter 配置 |
| X2Text Service | unstract-x2text-service |
3004 | 文本抽取(executor 依赖) |
| Runner | unstract-runner |
5002 | 非 structure 类工具(Classifier 等) |
| Frontend | unstract-frontend |
3000 | Web UI |
| Flipt | unstract-flipt |
8082 (REST)、9005 (gRPC) | 特性开关 |
3.3 V2 统一 Worker(--profile workers-v2)
| Worker | 容器 | 健康端口 | 队列 |
|---|---|---|---|
| Executor | unstract-worker-executor-v2 |
8088 | executor(见下方源码说明) |
| File Processing | unstract-worker-file-processing-v2 |
8082 | file_processing、api_file_processing |
| API Deployment | unstract-worker-api-deployment-v2 |
8090 | celery_api_deployments |
| Callback | unstract-worker-callback-v2 |
8083 | file_processing_callback、api_file_processing_callback |
| General | unstract-worker-general-v2 |
8082 | celery |
| Notification | unstract-worker-notification-v2 |
8085 | notifications、notifications_* |
| Log Consumer | unstract-worker-log-consumer-v2 |
8084 | celery_log_task_queue |
| Scheduler | unstract-worker-scheduler-v2 |
8087 | scheduler |
源码注: 从当前 docker/docker-compose.yaml 看,executor worker 的监听队列由环境变量
CELERY_QUEUES_EXECUTOR决定,默认值为celery_executor_legacy,celery_executor_agentic,celery_executor_agentic_table;workers/executor/worker.py 的check_executor_health也直接读取该变量。文档写作时期简称为executor队列,实操时请以.env/ compose 中的实际取值为准。
3.4 迁移后被移除的服务
| 服务 | 端口 | 替代者 |
|---|---|---|
| Executor Worker(LegacyExecutor 内联执行) | ||
| N/A | structure_tool_task(Celery 任务) |
4. 分步部署
4.1 启动基础基础设施
cd docker
# 仅启动基础设施服务
docker compose -f docker-compose-dev-essentials.yaml up -d
等待所有服务进入 healthy 状态:
docker compose -f docker-compose-dev-essentials.yaml ps
(docker-compose-dev-essentials.yaml 即上文文件 docker/docker-compose-dev-essentials.yaml。)
4.2 启动应用服务
方案 A:全部通过 Docker Compose(推荐首次部署)
cd docker
# 启动全部组件,包括带 executor 的 V2 worker
docker compose --profile workers-v2 up -d
方案 B:混合模式(服务进 Docker,worker 本地跑)
适合需要频繁迭代 worker 代码、不想反复构建镜像的场景:
# 只启动基础设施 + 应用服务(不含 V2 worker)
docker compose up -d
# 然后在本地运行 executor worker(见第 6 节)
4.3 验证数据库迁移
Backend 容器启动时会自动执行迁移(--migrate 参数),可验证:
docker logs unstract-backend 2>&1 | grep -i "migration"
4.4 为本地开发创建 workers 的 .env
如果在 Docker 之外运行 worker,需要本地 .env:
cd workers
# 复制样例并按本地开发调整
cp sample.env .env
样例文件为 workers/sample.env。编辑 workers/.env,将所有 Docker 服务名改为 localhost:
# === 本地开发的关键改动 ===
DJANGO_APP_BACKEND_URL=http://localhost:8000
INTERNAL_API_BASE_URL=http://localhost:8000/internal
CELERY_BROKER_BASE_URL=amqp://localhost:5672//
DB_HOST=localhost
REDIS_HOST=localhost
CACHE_REDIS_HOST=localhost
PLATFORM_SERVICE_HOST=http://localhost
PLATFORM_SERVICE_PORT=3001
PROMPT_HOST=http://localhost
PROMPT_PORT=3003
X2TEXT_HOST=http://localhost
X2TEXT_PORT=3004
UNSTRACT_RUNNER_HOST=http://localhost
UNSTRACT_RUNNER_PORT=5002
WORKFLOW_EXECUTION_FILE_STORAGE_CREDENTIALS='{"provider": "minio", "credentials": {"endpoint_url": "http://localhost:9000", "key": "minio", "secret": "minio123"}}'
API_FILE_STORAGE_CREDENTIALS='{"provider": "minio", "credentials": {"endpoint_url": "http://localhost:9000", "key": "minio", "secret": "minio123"}}'
重要:
INTERNAL_SERVICE_API_KEY必须与 backend 侧期望一致,开发环境默认值为dev-internal-key-123。
5. 环境配置详解
5.1 Executor Worker 关键环境变量
| 变量 | Docker 默认值 | 本地覆盖值 | 用途 |
|---|---|---|---|
CELERY_BROKER_BASE_URL |
amqp://unstract-rabbitmq:5672// |
amqp://localhost:5672// |
RabbitMQ 连接 |
CELERY_BROKER_USER |
admin |
同左 | RabbitMQ 用户 |
CELERY_BROKER_PASS |
password |
同左 | RabbitMQ 密码 |
DB_HOST |
unstract-db |
localhost |
PostgreSQL(result backend) |
DB_USER |
unstract_dev |
同左 | DB 用户 |
DB_PASSWORD |
unstract_pass |
同左 | DB 密码 |
DB_NAME |
unstract_db |
同左 | 数据库名 |
DB_PORT |
5432 |
同左 | DB 端口 |
REDIS_HOST |
unstract-redis |
localhost |
Redis 缓存 |
PLATFORM_SERVICE_HOST |
http://unstract-platform-service |
http://localhost |
Platform 服务地址 |
PLATFORM_SERVICE_PORT |
3001 |
同左 | Platform 服务端口 |
X2TEXT_HOST |
http://unstract-x2text-service |
http://localhost |
X2Text 服务地址 |
X2TEXT_PORT |
3004 |
同左 | X2Text 服务端口 |
INTERNAL_SERVICE_API_KEY |
dev-internal-key-123 |
同左 | Worker → Backend 认证 |
INTERNAL_API_BASE_URL |
http://unstract-backend:8000/internal |
http://localhost:8000/internal |
Backend 内部 API |
WORKFLOW_EXECUTION_FILE_STORAGE_CREDENTIALS |
(MinIO JSON,Docker 主机名) | (MinIO JSON,localhost) | 共享文件存储 |
5.2 Executor 专属运行参数(来自 sample.env 与 worker 文档)
以下参数在 workers/sample.env 中定义了默认值,与 workers/executor/README.md 的说明一致:
| 变量 | 默认值 | 说明 |
|---|---|---|
WORKER_EXECUTOR_CONCURRENCY |
2 |
executor 并发进程数 |
WORKER_EXECUTOR_POOL |
prefork |
Celery 池类型 |
EXECUTOR_TASK_TIME_LIMIT |
3600 |
每任务硬超时(秒) |
EXECUTOR_TASK_SOFT_TIME_LIMIT |
3300 |
每任务软超时(秒) |
EXECUTOR_RESULT_TIMEOUT |
3600 |
调用方等待结果的最长时间 |
EXECUTOR_AUTOSCALE |
2,1 |
自动扩缩容 max,min |
EXECUTOR_HEALTH_PORT |
8088 |
健康检查端口 |
5.3 默认开发凭据参考
| 服务 | 用户名 | 密码 |
|---|---|---|
| PostgreSQL | unstract_dev |
unstract_pass |
| RabbitMQ | admin |
password |
| MinIO | minio |
minio123 |
| Redis | (无) | (无) |
5.4 分层式 Celery 配置
Worker 配置采用三层优先级体系(越具体者越优先):
- Worker 专属: 如
EXECUTOR_TASK_TIME_LIMIT=7200; - 全局 Celery: 如
CELERY_TASK_TIME_LIMIT=3600; - 代码内置默认值:(硬编码兜底)。
从源码结构看,这一机制由 workers/shared/ 中的 get_celery_setting(定义于 workers/shared/models/worker_models.py)实现,workers/worker.py 中 HeartbeatKeeper 的 shutdown_interval、normal_check_interval 等参数即按「CLI 参数 > worker 专属 > 全局 > 默认」的顺序解析。
6. 运行 Executor Worker
6.1 通过 Docker Compose(最简)
cd docker
# 只启动 executor worker(假设基础设施已运行)
docker compose --profile workers-v2 up -d worker-executor-v2
# 查看日志
docker logs -f unstract-worker-executor-v2
compose 中该服务定义为 worker-executor-v2(容器名 unstract-worker-executor-v2),健康端口通过 EXECUTOR_METRICS_PORT=8088 注入,并统一使用 worker-unified 镜像。
6.2 本地使用 run-worker.sh
cd workers
# 确保 .env 已按 4.4 节完成本地化
./run-worker.sh executor
脚本为 workers/run-worker.sh,支持以下选项:
./run-worker.sh -l DEBUG executor # 调试日志
./run-worker.sh -c 4 executor # 4 个并发任务
./run-worker.sh -P threads executor # 线程池替代 prefork
./run-worker.sh -d executor # 后台(分离)运行
./run-worker.sh -s # 查看所有 worker 状态
./run-worker.sh -k # 结束所有 worker
6.3 本地用 uv 手动启动
cd workers
# 加载环境变量
set -a && source .env && set +a
# 运行 executor worker
uv run celery -A worker worker \
--queues=celery_executor_legacy \
--loglevel=INFO \
--pool=prefork \
--concurrency=2 \
--hostname=executor-worker@%h
注意:
--queues应与 docker/docker-compose.yaml 中CELERY_QUEUES_EXECUTOR的默认值celery_executor_legacy保持一致(文档写作时期简写为executor)。
6.4 验证 Executor Worker 已就绪
# 检查健康端点
curl -s http://localhost:8088/health | python3 -m json.tool
# 检查 Celery 已注册的任务
uv run celery -A worker inspect registered \
--destination=executor-worker@$(hostname)
# 预期任务: execute_extraction
源码佐证:execute_extraction 在 workers/shared/enums/task_enums.py 中定义为 TaskName.EXECUTE_EXTRACTION = "execute_extraction",任务路由在 workers/shared/infrastructure/config/registry.py 中声明为 TaskRoute("execute_extraction", QueueName.EXECUTOR) —— 这正是「任务必须落到 executor 队列」的代码出处,排查"任务不执行"时应优先核对此处。
/health 端点的响应也不只是 {"status": "healthy"}:workers/executor/worker.py 注册的 check_executor_health 会额外返回已注册的 executor 列表(registered_executors)与当前监听队列(读取 CELERY_QUEUES_EXECUTOR),因此健康检查同时是执行器注册状态的探针。
6.5 运行全部 V2 Worker
# Docker 方式
cd docker && docker compose --profile workers-v2 up -d
# 脚本方式(本地)
cd workers && ./run-worker.sh all
7. 端口参考
7.1 基础设施
| 服务 | 端口 | 连接方式 |
|---|---|---|
| PostgreSQL | 5432 | psql -h localhost -U unstract_dev -d unstract_db |
| Redis | 6379 | redis-cli -h localhost |
| RabbitMQ AMQP | 5672 | amqp://admin:password@localhost:5672// |
| RabbitMQ 管理 UI | 15672 | http://localhost:15672 (admin/password) |
| MinIO S3 API | 9000 | http://localhost:9000 |
| MinIO Console | 9001 | http://localhost:9001 (minio/minio123) |
| Qdrant | 6333 | http://localhost:6333 |
| Traefik Dashboard | 8080 | http://localhost:8080 |
7.2 应用服务
| 服务 | 端口 | URL |
|---|---|---|
| Backend API | 8000 | http://localhost:8000/api/v1/ |
| Frontend | 3000 | http://frontend.unstract.localhost |
| Platform Service | 3001 | http://localhost:3001 |
| X2Text Service | 3004 | http://localhost:3004 |
| Runner | 5002 | http://localhost:5002 |
| Celery Flower(可选) | 5555 | http://localhost:5555 |
7.3 V2 Worker 健康端口
| Worker | 内部端口 | 外部端口 (Docker) |
|---|---|---|
| API Deployment | 8090 | 8085 |
| Callback | 8083 | 8086 |
| File Processing | 8082 | 8087 |
| General | 8082 | 8088 |
| Notification | 8085 | 8089 |
| Log Consumer | 8084 | 8090 |
| Scheduler | 8087 | 8091 |
| Executor | 8088 | 8092 |
7.4 调试端口(Docker dev 模式,经 compose.override.yaml 注入)
| 服务 | 调试端口 |
|---|---|
| Backend | 5678 |
| Runner | 5679 |
| Platform Service | 5680 |
| Prompt Service | 5681 |
| File Processing Worker | 5682 |
| Callback Worker | 5683 |
| API Deployment Worker | 5684 |
| General Worker | 5685 |
8. 健康检查端点
每个 V2 worker 都在其健康端口上暴露 GET /health:
# Executor worker(本地直连时)
curl -s http://localhost:8088/health
# 预期响应:
# {"status": "healthy", "worker_type": "executor", ...}
各 worker 端点一览(本地直跑 worker 的内部端口):
http://localhost:8080/health — API Deployment worker
http://localhost:8081/health — General worker
http://localhost:8082/health — File Processing worker
http://localhost:8083/health — Callback worker
http://localhost:8084/health — Log Consumer worker
http://localhost:8085/health — Notification worker
http://localhost:8087/health — Scheduler worker
http://localhost:8088/health — Executor worker
在 Docker 外部访问时,请使用 7.3 节中对应的外部端口映射(例如 executor 为 8092)。
9. 调试与故障排查
9.1 常见问题
RabbitMQ/Redis/DB 报 "Connection refused"
- 确认容器在运行:
docker ps; - 确认
.env中用的是 Docker 服务名还是localhost(见 5.1); - 确认端口已暴露:
docker port unstract-rabbitmq。
Executor worker 启动了但任务不执行
- 检查队列绑定:worker 必须监听 executor 队列(本地以
CELERY_QUEUES_EXECUTOR实际值为准,默认celery_executor_legacy); - 打开 RabbitMQ 管理 UI(http://localhost:15672)→ Queues 页签,确认对应队列存在且有 consumer;
- 检查任务是否注册:
celery -A worker inspect registered; - 核对任务路由:workers/shared/infrastructure/config/registry.py 中
TaskRoute("execute_extraction", QueueName.EXECUTOR)。
Executor worker 中出现 "Module not found"
- 确保
PYTHONPATH包含 workers 目录; - 本地运行时先
cd workers再启动; - 使用
run-worker.sh时它会自行设置 PYTHONPATH(workers/run-worker.sh)。
MinIO 文件访问错误
- 检查
WORKFLOW_EXECUTION_FILE_STORAGE_CREDENTIALS中的 endpoint 是 localhost 还是 Docker 服务名; - 确认 bucket 存在:
mc ls minio/unstract/; - MinIO bootstrap 容器会在首次启动时创建 bucket。
Platform service 连接错误
- Executor 需要
PLATFORM_SERVICE_HOST与PLATFORM_SERVICE_PORT; - 验证 platform-service 存活:
curl http://localhost:3001/health。
9.2 常用调试命令
# 查看全部容器
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
# 查看 RabbitMQ 队列
docker exec unstract-rabbitmq rabbitmqctl list_queues name messages consumers
# 查看 Celery worker 状态(在 workers/ 目录)
cd workers && uv run celery -A worker inspect active
# 查看已注册任务
cd workers && uv run celery -A worker inspect registered
# 向 executor 发送一个测试任务
cd workers && uv run python -c "
from worker import app
from shared.enums.task_enums import TaskName
result = app.send_task(
TaskName.EXECUTE_EXTRACTION,
args=[{
'executor_name': 'legacy',
'operation': 'extract',
'run_id': 'test-123',
'execution_source': 'tool',
'executor_params': {}
}],
queue='celery_executor_legacy'
)
print(f'Task ID: {result.id}')
print(f'Result: {result.get(timeout=30)}')
"
# 实时监听 Celery 事件
cd workers && uv run celery -A worker events
# 查询 Celery result backend(Postgres)
docker exec -it unstract-db psql -U unstract_dev -d unstract_db \
-c "SELECT task_id, status FROM public.celery_taskmeta ORDER BY date_done DESC LIMIT 10;"
注意测试任务的
queue参数应与 worker 实际监听队列一致(当前默认celery_executor_legacy)。
从源码看,execute_extraction 任务本身对 ConnectionError、TimeoutError、OSError 配置了 autoretry_for(最多 3 次、指数退避、带抖动,见 workers/executor/tasks.py),因此偶发的网络类失败不应直接当作任务失败处理;此外任务执行成功后会尝试把 usage_records 通过 UsageAPIClient 批量写入账单表,失败时只记录 ERROR 日志而不阻断任务返回。
9.3 日志位置
| 场景 | 位置 |
|---|---|
| Docker 容器 | docker logs <container-name> |
| 本地 worker(前台) | stdout/stderr |
| 本地 worker(分离运行) | workers/<worker_type>/<worker_type>.log |
| Backend | docker logs unstract-backend |
10. 测试验证清单
阶段 1:Executor 框架基线
- [ ] Executor worker 启动并连上 Celery broker
- [ ] 健康检查可达:
curl http://localhost:8088/health - [ ]
execute_extraction任务已注册进 Celery - [ ] No-op 任务分发能成功往返
- [ ] 任务路由正确:任务进入 executor 队列、由 executor worker 消费
阶段 2:LegacyExecutor 基线
- [ ]
extract操作返回{"extracted_text": "..."} - [ ]
index操作返回{"doc_id": "..."} - [ ]
answer_prompt返回{"output": {...}, "metadata": {...}, "metrics": {...}} - [ ]
single_pass_extraction返回与 answer_prompt 相同的结构 - [ ]
summarize返回{"data": "..."} - [ ] 错误场景返回
ExecutionResult(success=False, error="...")而非未捕获异常
阶段 3:Structure Tool 作为 Celery 任务
- [ ] 通过新的 Celery 路径运行带 structure tool 的 workflow
- [ ] 输出与 Docker 版 structure tool 的输出一致
- [ ] 非 structure 工具仍走 Docker/Runner(回归检查)
阶段 4:IDE 路径
- [ ] 打开 Prompt Studio IDE,创建/加载项目
- [ ] 对文档执行抽取 —— 结果正确展示
- [ ] 执行 prompt 问答 —— 输出持久化到 DB
- [ ] 错误场景在 IDE 中正确展示
阶段 5:下线确认(Decommission)
- [ ]
docker compose up干净启动 —— 无缺失服务报错 - [ ] 代码中不再有指向 prompt-service、PromptTool、PROMPT_HOST、PROMPT_PORT 的悬空引用
- [ ] 所有健康检查通过
运行单元测试
# SDK1 测试(execution 框架:context / dispatcher / orchestrator / registry / result)
cd unstract/sdk1
uv run pytest -v
# Workers 测试(executor、LegacyExecutor、retrievers 等)
cd workers
uv run pytest -v
相关测试目录与文件:workers/tests/(含 test_executor_sanity.py、test_executor_rpc.py、test_summarize_operation.py 等)与 unstract/sdk1/tests/。execution 框架核心实现位于 unstract/sdk1/src/unstract/sdk1/execution/,包含 context.py、dispatcher.py、executor.py、orchestrator.py、registry.py、result.py 六个模块,是理解"分发 → 编排 → 注册 → 结果"调用链的最佳入口。
11. 快速参考:一行式部署
# 从仓库根目录:
cd docker
# 1. 构建镜像
docker compose -f docker-compose.build.yaml build
# 2. 启动全部组件(含 V2 worker)
docker compose --profile workers-v2 up -d
# 3. 验证容器
docker ps --format "table {{.Names}}\t{{.Status}}"
# 4. 检查 executor 健康(8092 = Docker 外部端口)
curl -s http://localhost:8092/health
自动化版本可使用原文档提到的 setup 检查脚本 scripts/check-local-setup.sh。
12. 源码纵深:这条链路在仓库里对应什么
为便于从本文档继续深入仓库,以下列出关键实现位置(相对仓库根目录):
| 组件 | 路径 | 说明 |
|---|---|---|
| 统一 worker 入口 | workers/worker.py | 依据 WORKER_TYPE 环境变量用 WorkerBuilder 构建 Celery app;注册 HeartbeatKeeper(warm shutdown 期间保持 RabbitMQ 心跳,防止 K8s 终止时任务重复投递);空任务注册表检测 |
| Executor worker 定义 | workers/executor/worker.py | WorkerType.EXECUTOR、健康检查 executor_health、导入期触发 executor 注册 |
execute_extraction 任务 |
workers/executor/tasks.py | 单点入口:ExecutionContext.from_dict → ExecutionOrchestrator.execute → 用量记录 → result.to_dict() |
| Execution 框架 | unstract/sdk1/src/unstract/sdk1/execution/ | ExecutionContext / ExecutionOrchestrator / ExecutorRegistry / ExecutionResult / ExecutionDispatcher |
| 任务路由 | workers/shared/infrastructure/config/registry.py | TaskRoute("execute_extraction", QueueName.EXECUTOR) |
| 任务枚举 | workers/shared/enums/task_enums.py | EXECUTE_EXTRACTION = "execute_extraction" |
| Compose 定义 | docker/docker-compose.yaml | worker-executor-v2 服务:EXECUTOR_METRICS_PORT=8088、CELERY_QUEUES_EXECUTOR、并发/池参数 |
| 本地环境变量样例 | workers/sample.env | EXECUTOR_* 系列默认值 |
| 本地启动脚本 | workers/run-worker.sh | -l/-c/-P/-d/-s/-k 选项 |
| Structure Tool 任务 | workers/file_processing/structure_tool_task.py | 替代原 Docker 版 structure tool 的 Celery 实现 |
需要牢记的三个实操要点:其一,本地运行 worker 时 .env 中所有 Docker 服务名必须替换为 localhost,INTERNAL_SERVICE_API_KEY 必须与 backend 一致;其二,executor 的监听队列以 CELERY_QUEUES_EXECUTOR 当前取值为准(默认 celery_executor_legacy),手动发送测试任务时队列名必须与之一致;其三,本文档对应的开发分支为 feat/execution-backend,迁移不产生数据库 schema 变更,因此无需额外执行 Django 迁移即可验证全部阶段。