Unstract Backend 完全指南Django Celery 后端服务的本地搭建、异步队列与 API 契约管理【免费下载链接】unstractLLM-Driven Extraction of Unstructured Data — Built for API Deployments ETL Pipeline Workflows项目地址: https://gitcode.com/GitHub_Trending/un/unstract本文基于 Unstract 仓库的 backend/README.md 展开系统讲解该 Django/DRF 后端服务的依赖环境搭建、环境变量配置、默认账号认证体系、基于 Celery RabbitMQ 的异步执行架构队列、autoscaling、监控面板、Postgres 直连操作以及 API 部署 OpenAPI 契约的生成与漂移检查机制。读完后可独立完成后端本地启动、Worker 拉起、凭据定制和 spec 重新生成。一、定位与核心依赖Unstract 后端由 Django 与 Django REST Framework 编写负责构建和调度围绕非结构化数据的 ETL 流水线。仓库中 backend/pyproject.toml 明确其项目描述为 Unstract backend built with Django to build and schedule ETL pipelines around unstructured data要求 Python3.12,3.13核心依赖包括django4.2.30、djangorestframework3.17.1、celery[amqp]5.3.4、django-celery-beat2.5.0、django-redis5.4.0、drf-spectacular0.30.0等并内嵌引用了unstract-core、unstract-connectors、unstract-tool-registry等本仓库内的可编辑editable本地包。后端运行依赖三个外部基础设施README 明确列出Postgres— 主数据库Redis— 缓存、日志与状态跟踪如执行状态 tracker、限流锁RabbitMQ— Celery 消息 Broker。从 backend/sample.env 可以看到三者的连接变量约定# Postgres DB envs DB_HOSTunstract-db DB_USERunstract_dev DB_PASSWORDunstract_pass DB_NAMEunstract_db DB_PORT5432 DB_SCHEMAunstract # Redis REDIS_HOSTunstract-redis REDIS_PORT6379 REDIS_PASSWORD REDIS_USERdefault # Celery Configuration # Used by celery and to connect to queue to push logs CELERY_BROKER_BASE_URLamqp://unstract-rabbitmq:5672// CELERY_BROKER_USERadmin CELERY_BROKER_PASSpassword二、本地安装与启动2.1 创建虚拟环境基于 UV所有命令假设已在backend/目录内激活venv并假定已安装 UV# Create venv and install dependencies uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv sync2.2 依赖安装分组backend/pyproject.toml 通过[dependency-groups]声明了三组依赖可精确安装# Install dependencies uv sync # Install specific dev dependency grouppytest、poethepoet、debugpy 等 uv sync --group dev # Install production dependencies onlygunicorn、OpenTelemetry 等 uv sync --group deploy从 pyproject.toml 的分组定义看dev组包含pytest、poethepoet、debugpy、inotify文件监听以及本地unstract-*包test组单独声明了pytest-django与jsonschema注释说明 schema 测试直接 import jsonschema显式声明可避免传递依赖变化导致测试静默跳过deploy组包含gunicorn~23.0与 OpenTelemetry 发行包。此外[tool.uv.constraint-dependencies]将numpy2.0.0、pandas2.2.0作为约束以解决 Python 3.12 与 Numpy 2.0 的兼容问题。2.3 脚本与命令执行UV 支持直接运行服务目录内的脚本uv run sample_script.py2.4 配置 .env 并启动服务器按计划启动 Django 服务器前需确保 Postgres/Redis/RabbitMQ 已就绪本地或 docker compose 方式。将sample.env复制为.env并按需修改本地直连的典型取值如下README 原文示例DJANGO_SETTINGS_MODULEbackend.settings.dev DB_HOSTlocalhost DB_USERunstract_dev DB_PASSWORDunstract_pass DB_NAMEunstract_db DB_PORT5432其中DJANGO_SETTINGS_MODULE指向 backend/backend/settings/dev.py该模块在 base.py 基础上开启DEBUG True并追加localhost:3000、frontend.unstract.localhost等 CORS 来源适合本地联调。随后应用迁移并启动开发服务器# 若修改过模型先生成迁移 uv run manage.py makemigrations # 应用迁移并启动服务 uv run manage.py migrate uv run manage.py runserver localhost:8000服务启动后运行在 8000 端口http://localhost:8000。补充生产容器内不走runserver而是通过 backend/entrypoint.sh 以 Gunicorn 启动--worker-class gthreadGUNICORN_WORKERS/GUNICORN_THREADS环境变量可调。脚本注释解释了一个关键调参逻辑Gunicorn 线程数必须大于并发浏览器标签数因为每个打开的 Socket.IO WebSocket 会独占一个线程直至关闭线程池惰性创建因此高上限在空闲时零成本。三、认证体系默认凭据与修改规范3.1 默认账号首次部署的默认登录凭据为用户名unstract密码unstract。这一默认值来自 backend/backend/settings/base.py 中的DEFAULT_AUTH_USERNAME os.environ.get(DEFAULT_AUTH_USERNAME, unstract)即环境变量未设置时回退到unstract。3.2 初始化自定义凭据如需修改默认用户名/密码打开由 backend/sample.env 复制生成的/backend/.env将DEFAULT_AUTH_USERNAME与DEFAULT_AUTH_PASSWORD更新为强且唯一的凭据保存并重启服务使变更生效。sample.env中对应位置默认留空空值即回退默认凭据# Default user auth credentials DEFAULT_AUTH_USERNAME DEFAULT_AUTH_PASSWORD3.3 初始化之后更新凭据首次部署后更新方式相同修改/backend/.env中DEFAULT_AUTH_USERNAMEyour_new_username、DEFAULT_AUTH_PASSWORDyour_new_password保存后重启backend服务之后即可用新凭据登录。3.4 重要注意事项DEFAULT_AUTH_USERNAME不得与任何 Django superuser 或 admin 账号的username相同保持二者分离以确保安全、避免冲突使用强且唯一的凭据保护系统认证系统会以/backend/.env中指定的值校验凭据。从源码结构看MOCK_USER等内部常量直接引用settings.DEFAULT_AUTH_USERNAME见 backend/account_v2/constants.py说明该变量同时参与内部用户模拟逻辑改动时需注意其影响面。四、异步执行Celery 队列、Worker 与监控项目使用 Celery 处理异步执行任务经多个队列分发、由 Worker 消费。README 强调ETL、TASK 与 API Deployment 任务均由这些异步 Worker 处理日志管理同样依赖 Celery。4.1 队列一览Queue Name说明承载任务celery默认队列处理未指定队列的通用任务Webhook 通知、PipelineETL、Tasks执行celery_periodic_logs将日志持久化到数据库的队列—celery_log_task_queue向 WebSocket 客户端推送日志的队列—celery_api_deployments管理 API 部署任务的队列—从 backend/backend/celery_config.py 可以印证并补充更多细节结果后端Celery 结果直接写入 Postgresresult_backend为dbpostgresql://.../{CELERY_BACKEND_DB_NAME}CELERY_BACKEND_DB_NAME可选默认回退到DB_NAME见sample.env注释序列化任务与结果统一 JSONtask_serializer json并开启result_extended True调度器beat_scheduler django_celery_beat.schedulers:DatabaseScheduler周期任务存库管理task_acks_late True任务确认延后到执行完成降低 Worker 崩溃时任务丢失的风险HA 模式当RABBITMQ_HA_ENABLEDtrue时配置在 import 期将celery、celery_api_deployments、celery_periodic_logs、celery_log_task_queue、dashboard_metric_events五个队列声明为x-queue-type: quorumquorum 队列并将 QoS 语义改为 per-consumer prefetch因为 quorum 队列不支持 channel 级全局 QoS。4.2 启动执行 Workercelery -A backend worker --loglevelinfo -Q queue_name4.3 Worker 自动伸缩Autoscalingcelery -A backend worker --loglevelinfo -Q queue_name --autoscalemax_workers,min_workersCelery 支持按负载动态调整 Worker 进程数README 给出的取值建议max_workers与 CPU 资源和所需并发度相关。CPU 密集型任务设为接近或略高于 CPU 核心数I/O 密集型任务可设更高通常为 CPU 核心数的 2–3 倍min_workers始终常驻的最少 Worker 进程数。实战佐证backend/pyproject.toml 的[tool.poe.tasks]中内置了 dashboard metrics Worker 的启动任务celery -A backend worker --loglevelinfo -Q dashboard_metric_events --autoscale 4,1即最大 4、常驻 1的伸缩配置可直接照抄到自己的队列上。4.4 Worker 监控Flower前提当前环境已安装 flower 包。启动命令celery -A backend flowerFlower 默认监听 5555 端口浏览器访问即可获得友好的 Web 界面用于监控和管理 Celery 任务。pyproject.toml 中同样提供了等价任务poe flowercelery -A backend flower --port5555另有poe beat启动 Celery Beat 调度器、poe worker-metrics启动 metrics Worker。4.5 Broker 监控RabbitMQ 管理台RabbitMQ 自带 Web 管理界面访问http://localhost:15672默认凭据admin/password可通过环境变量RABBITMQ_DEFAULT_USER、RABBITMQ_DEFAULT_PASS配置README 指出其定义于 docker 侧的 essentials 环境文件。五、连接 Postgres连接 docker compose 中运行的 Postgres 的完整步骤进入 postgres 容器的 shelldocker compose exec -it db bash以指定用户连接数据库psql -d unstract_db -U unstract_dev在该 shell 中直接执行 PSQL 命令即可。六、API 文档OpenAPI 契约的提交与漂移检查API 部署端点的 OpenAPI 规范提交在 specs/docstudio-oss.json它是已发布客户端及其生成 SDK 的构建契约运行时并不提供该文件。规则是任何路由、serializer 或 schema 注解变更必须在同一个 PR中重新生成uv run python manage.py generate_docstudio_spec # 重写已提交的 spec uv run python manage.py generate_docstudio_spec --check # 只检查不落盘存在漂移则报错该命令的实现位于 backend/api_v2/management/commands/generate_docstudio_spec.py源码揭示了若干工程质量细节生成基于api_v2.deployment_spec_urls这份专用 URL 配置drf-spectacular的SchemaGenerator只覆盖 API 部署面若 spectacular 报告了任何解析 error/warning即存在猜测的 schema命令直接失败——宁可失败也不发布一份描述不出真实行为的契约生成的路径必须全部位于公共挂载前缀/deployment/之下若检测到API_DEPLOYMENT_PATH_PREFIX改变了挂载点而污染了产物会拒绝生成产物使用sort_keys的规范化 JSON 输出使字节级一致成为可用的漂移信号--check模式下磁盘文件与重新渲染结果不一致即报out of date并提示下游unstract-python-client与unstract-cli需要联动发 PR。配套的漂移测试见 backend/api_v2/tests/test_docstudio_spec.py它与命令共享同一渲染函数避免校验用的副本与生成产物不一致。README 同时索引了两份端点级文档Accountaccount/api_doc.md与 FileManagement。七、连接器Google DriveGoogle Drive 连接器基于 PyDrive2 库实现且仅支持 OAuth 2.0 认证。配置步骤按 Google OAuth 文档完成客户端凭据申请然后在backend/.env中填入GOOGLE_OAUTH2_KEYclient-id GOOGLE_OAUTH2_SECRETclient-secret这两个变量在 backend/sample.env 中对应GOOGLE_OAUTH2_KEY与GOOGLE_OAUTH2_SECRET默认空。此外sample.env还预留了 SharePoint 的 Azure AD OAuth 变量AZUREAD_TENANT_OAUTH2_KEY/SECRET配合social-auth-app-django实现第三方授权。八、Tool Registry工具的添加与维护机制在 unstract/tool-registry/README.md 中有专门说明。后端通过TOOL_REGISTRY_CONFIG_PATHsample.env中默认/data/tool_registry_config指定工具注册目录TOOL_REGISTRY_STORAGE_CREDENTIALS指定其存储后端示例为 local。九、附录Archived / EXPERIMENTAL以下内容在 README 中标记为归档实验性内容。9.1 访问 Admin 站点首次使用时创建 superuser按屏幕提示操作python manage.py createsuperuser在app/admin.py中注册模型例如from django.contrib import admin from .models import Prompt admin.site.register(Prompt)确保服务器运行后访问/admin端点。注意这与 3.4 节的安全约束呼应——admin/superuser 账号与DEFAULT_AUTH_USERNAME应保持分离。9.2 运行单元测试单元测试基于 pytest 与 pytest-djangopytest pytest prompt # 运行名为 prompt 的 app测试按 app 组织例如prompt/tests/test_urls.py。注意运行测试不需要 Django 服务器在线但数据库必须在运行。从 backend/pyproject.toml 的[tool.pytest.ini_options]可见默认addopts --no-migrations跳过迁移回放、直接从模型建表避免 xdist 每个 Worker 重放一遍迁移历史python_files同时匹配test_*.py、*_test.py、*_tests.py、tests.py并定义了integration需要真实 Postgres/Redis 基础设施与critical_path(path_id)配合tests/critical_paths.yaml声明关键路径覆盖两个 marker。测试环境变量由 backend/conftest.py 通过 python-dotenv 直接加载test.env仓库提供 backend/sample.test.env。十、快速核对清单事项命令 / 入口安装依赖uv sync可选--group dev/--group deploy数据库迁移uv run manage.py migrate启动开发服务器uv run manage.py runserver localhost:8000启动指定队列 Workercelery -A backend worker --loglevelinfo -Q queue_nameFlower 监控celery -A backend flower端口 5555RabbitMQ 管理台http://localhost:15672admin / password重新生成 OpenAPI 契约uv run python manage.py generate_docstudio_spec [--check]进入 Postgresdocker compose exec -it db bash→psql -d unstract_db -U unstract_dev以上内容与 backend/README.md 保持一致并以仓库内 backend/pyproject.toml、backend/sample.env、backend/backend/celery_config.py、backend/entrypoint.sh 及 backend/api_v2/management/commands/generate_docstudio_spec.py 的源码实现作为佐证。适用前提Python 3.12、UV 工具链以及 Postgres/Redis/RabbitMQ 三项依赖可用本地进程或 docker compose 服务名均可。【免费下载链接】unstractLLM-Driven Extraction of Unstructured Data — Built for API Deployments ETL Pipeline Workflows项目地址: https://gitcode.com/GitHub_Trending/un/unstract创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考