Label Studio 启动完全指南：命令行参数、环境变量与多种部署方式实战

Label Studio 启动完全指南命令行参数、环境变量与多种部署方式实战【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio安装好 Label Studio 之后启动服务器是使用它的第一步。本文基于 Label Studio 官方启动指南docs/source/guide/start.md结合仓库源码label_studio/server.py、label_studio/core/argparser.py完整讲解如何用一条命令启动服务、全部命令行参数与环境变量的含义与默认值、如何修改端口、如何运行在 Docker、如何暴露到公网ngrok、如何使用本地文件存储、如何配置 HTTPS、外部域名与 Heroku 部署以及如何为项目设置任务采样顺序。读完本文你将能根据任何部署场景准确组合出可运行的启动命令。快速开始启动 Label Studio 服务器安装完成后在终端执行label-studio start默认情况下Label Studio 使用 SQLite 数据库label_studio.sqlite3来存储标注任务与标注结果。你也可以通过 Label Studio 界面或 API 为任务和标注指定不同的数据源与目标存储详见 Database storage。从源码看label-studio命令最终进入 label_studio/server.py 的main()函数它先解析命令行参数label_studio/core/argparser.py再执行数据库迁移、创建默认用户、检查端口占用最后启动 Django 服务器若未指定--no-browser还会自动打开浏览器。命令行参数全解运行label-studio --help可以查看所有可用选项。下面的命令提供信息或执行特定操作命令说明label-studio启动 Label Studio 服务器。label-studio -h、label-studio --help显示可用的命令行参数。label-studio init project_name optional_arguments初始化 Label Studio 中的特定项目。label-studio start project_name --init optional_arguments启动 Label Studio 服务器并初始化特定项目。label-studio reset_password重置某个 Label Studio 用户的密码。参见 Create user accounts for Label Studio。label-studio shell进入 Label Studio 的 shell 以直接操作数据。参见 Django 的 shell_plus 文档。label-studio version显示 Label Studio 版本号并退出。label-studio user --username email显示指定用户的账号信息含 API token。源码中的子命令定义见 label_studio/core/argparser.py除上述命令外还包含calculate_stats_all_orgs重算任务计数与统计和export按指定格式导出项目等子命令。可选参数与环境变量下面的可选参数既可以作为label-studio start argument value传给命令行也可以设置成环境变量命令行参数环境变量默认值说明-b、--no-browserN/AFalse启动时不自动打开浏览器。-db、--databaseLABEL_STUDIO_DATABASElabel_studio.sqlite3指定用于存储任务与标注的数据库文件路径。参见 Database storage。--data-dirLABEL_STUDIO_BASE_DATA_DIR随操作系统而异存放所有应用相关数据的目录。-d、--debugN/AFalse开启调试模式以排查问题。-c、--configCONFIG_PATHdefault_config.json已废弃不要使用。指定服务器配置文件路径。-l、--label-configLABEL_STUDIO_LABEL_CONFIGNone指定项目标注配置文件XML路径。参见 Set up your labeling project。--ml-backendsN/ANone已废弃。指定一个或多个机器学习后端 URL。参见 Set up machine learning with your labeling process。--samplingN/Asequential指定任务顺序取值sequential或uniform。参见本文设置任务采样一节。--log-levelN/AERROR日志级别DEBUG、INFO、WARNING或ERROR。-p、--portLABEL_STUDIO_PORT8080指定 Web 服务器端口。参见本文localhost 端口一节。--hostLABEL_STUDIO_HOST指定生成导入任务链接或静态资源加载链接所用的主机名。留空则所有路径相对于根域名。例如https://77.42.77.42:1234或http://ls.example.com/subdomain/。参见本文外部域名一节。--certLABEL_STUDIO_CERT_FILENone已废弃不要使用。HTTPS 访问证书文件须为 PEM 格式。参见本文HTTPS一节。--keyLABEL_STUDIO_KEY_FILENone已废弃不要使用。HTTPS 私钥文件须为 PEM 格式。参见本文HTTPS一节。--initial-project-descriptionLABEL_STUDIO_PROJECT_DESC指定项目描述。参见 Set up your labeling project。--passwordLABEL_STUDIO_PASSWORDNone默认用户的密码。参见 Set up user accounts。--usernameLABEL_STUDIO_USERNAMEdefault_userlocalhost默认用户的用户名。参见 Set up user accounts。--user-tokenLABEL_STUDIO_USER_TOKEN自动生成用户调用 API 的认证 token。必须与用户名一起设置否则自动生成。参见 Set up user accounts。--agree-fix-sqliteN/AFalse在 Windows 上使用 Python 3.6–3.8 时自动同意修复 SQLite 问题。--enable-legacy-api-tokenLABEL_STUDIO_ENABLE_LEGACY_API_TOKENFalse启用旧版 API token 认证便于通过--user-token使用既有 token。N/ALABEL_STUDIO_LOCAL_FILES_SERVING_ENABLEDFalse允许 Label Studio 访问本地文件目录作为导入存储。参见本文Docker 本地存储一节。N/ALABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT/指定 Label Studio 访问本地文件目录时的根目录。参见本文Docker 本地存储一节。注意参数表中标注已废弃的选项--config、--ml-backends、--cert、--key在最新版本中已不建议使用。例如在 label_studio/server.py 中当检测到同时传入--cert与--key时服务器会直接报错并拒绝启动提示改用 NGINX 等反向代理来实现 HTTPS。源码视角参数解析与默认值表内的默认值可以在两处源码得到印证label_studio/core/argparser.py 中argparse为每个参数声明了choices与default例如--sampling的可选值[sequential, uniform, prediction-score-min]默认sequential--log-level的可选值[DEBUG, INFO, WARNING, ERROR]。label_studio/server.py 的main()会把部分参数转写为环境变量例如--database会设置DATABASE_NAME--data-dir会设置LABEL_STUDIO_BASE_DATA_DIR--host会设置HOSTlabel_studio/core/settings/base.py 再据此推导HOSTNAME并校验必须带http://或https://前缀、且不允许以/结尾。端口解析在 label_studio/server.pyinternal_port input_args.port or get_env(PORT) or config.get(port, 8080)即命令行--port优先级最高其次环境变量PORT最后配置文件默认 8080随后_get_free_port()在非调试模式下会自动探测并顺延到可用端口。设置环境变量如何设置环境变量取决于操作系统与部署环境。在 *nix 系统中可以从命令行或环境配置文件设置例如export LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLEDtrue注意如果使用 Docker可以将所有环境变量写入.env文件由 Docker Compose 自动加载。在 Windows 上使用如下语法set LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLEDtrue验证环境变量是否设置成功*nix 系统运行echo $LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLEDWindows 系统运行echo %LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED%在 localhost 上使用不同端口运行默认端口为 8080。如果该端口被占用或想换一个端口执行label-studio start --port port例如启动在 9001 端口label-studio start --port 9001或者设置环境变量LABEL_STUDIO_PORT 9001在 Docker 上使用不同端口运行使用 Docker 运行 Label Studio 并暴露非 8080 端口时在启动命令中指定端口映射即可。例如让容器对外暴露 9001 端口docker run -it -p 9001:8080 -v $(pwd)/mydata:/label-studio/data heartexlabs/label-studio:latest label-studio重要这是一个非 root 容器挂载的文件和目录必须对UID 1001具有适当的权限。如果使用 Docker Compose修改所使用docker-compose.yml中 NGINX 服务对外暴露的端口NGINX 用于反向代理 Label Studio。例如下面这段 docker-compose.yml 片段将代理端口从 80 改为 9001... nginx: image: nginx:latest ports: - 9001:80 depends_on: - app ...在 Docker 上使用主机名与子路径运行如果想在 Docker 中指定外部主机名与子路径只需把LABEL_STUDIO_HOST环境变量含子路径传给 docker/docker-composeLABEL_STUDIO_HOSThttp://localhost:8080/foo docker-compose up -d使用 ngrok 将本地实例暴露到公网有时你希望本地运行的 Label Studio 实例能被互联网访问例如与团队成员或客户共享。一种方式是使用 ngrok —— 一个能把本地实例暴露到公网的反向代理工具。如果 Label Studio 正在运行先停止它CtrlC。在 ngrok 官网注册一个免费账号。登录后按仪表盘指引安装并认证 ngrok。启动 ngrok 并指向 Label Studiongrok http --host-headerrewrite 8080输出中会生成一个随机 URL复制它。运行以下命令把your-subdomain.ngrok-free.app替换为你实际复制的 ngrok URLNative - Mac/Unix# 避免 CSRF 错误 # 必须与 ngrok 的 HTTPS URL 完全一致末尾不要带斜杠 export CSRF_TRUSTED_ORIGINShttps://your-subdomain.ngrok-free.app # 启动 Label Studio LABEL_STUDIO_HOSThttps://your-subdomain.ngrok-free.app label-studio startNative - Windows# 避免 CSRF 错误 # 必须与 ngrok 的 HTTPS URL 完全一致末尾不要带斜杠 set CSRF_TRUSTED_ORIGINShttps://your-subdomain.ngrok-free.app # 启动 Label Studio LABEL_STUDIO_HOSThttps://your-subdomain.ngrok-free.app label-studio startDocker 容器# 避免 CSRF 错误 # 必须与 ngrok 的 HTTPS URL 完全一致末尾不要带斜杠 docker run -it -p 8080:8080 \ -e CSRF_TRUSTED_ORIGINShttps://your-subdomain.ngrok-free.app \ -e LABEL_STUDIO_HOSThttps://your-subdomain.ngrok-free.app \ -v yourvolume:/label-studio/data \ heartexlabs/label-studio:latest重要这是一个非 root 容器挂载的文件和目录必须对UID 1001具有适当的权限。Docker Compose# 避免 CSRF 错误 # 必须与 ngrok 的 HTTPS URL 完全一致末尾不要带斜杠 CSRF_TRUSTED_ORIGINShttps://your-subdomain.ngrok-free.app \ LABEL_STUDIO_HOSThttps://your-subdomain.ngrok-free.app docker compose up -d完成后在浏览器中打开 ngrok URL确认能看到你的 Label Studio 实例。从源码看CSRF_TRUSTED_ORIGINS与 Django 的 CSRF 防护直接相关label_studio/core/settings/base.py 集中定义了CSRF_COOKIE_SECURE、CSRF_COOKIE_SAMESITE等配置域名不匹配会导致表单与 API 请求报 CSRF 校验失败而LABEL_STUDIO_HOST的作用则是让服务器生成的资源图片、音频等链接带有正确的外部域名。在 Docker 上使用本地存储要在 Docker 中引用宿主机上的持久化本地目录需要在启动容器时把目录挂载为卷并按需设置环境变量。下面的命令以最新镜像启动容器映射 8080 端口并通过环境变量允许 Label Studio 访问本地文件。示例中把宿主机目录./myfiles挂载到容器内的/label-studio/filesdocker run -it -p 8080:8080 -v $(pwd)/mydata:/label-studio/data \ --env LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLEDtrue \ --env LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT/label-studio/files \ -v $(pwd)/myfiles:/label-studio/files \ heartexlabs/label-studio:latest label-studio重要这是一个非 root 容器挂载的文件和目录必须对UID 1001具有适当的权限。设置LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT/label-studio/files后Label Studio 只扫描该目录下的本地文件。强烈建议显式指定LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT路径以限定容器对宿主机卷的访问范围、保障安全。将文件放入源目录本例为./myfiles然后在配置 local storage 时引用该目录。更多卷挂载用法参见 Docker 官方卷文档。如果使用 Docker Compose则在 YAML 文件中声明卷并把相关环境变量加到 app 容器上。源码视角本地文件服务的安全模型本地文件服务的底层实现位于 label_studio/io_storages/localfiles其要点如下两个环境变量的实际读取点在 label_studio/core/settings/base.pyLOCAL_FILES_SERVING_ENABLED默认FalseLOCAL_FILES_DOCUMENT_ROOT默认系统根目录两者均支持LABEL_STUDIO_或HEARTEX_前缀。若两者都未设置社区版会尝试自动探测当前目录下的mydata或label-studio-data目录并自动开启本地文件服务。文件通过/data/local-files/?d...端点提供访问该端点强制校验用户已认证、LOCAL_FILES_SERVING_ENABLEDtrue、请求文件位于某个 Local Files 导入存储路径之内、且用户对该存储所属项目有权限否则返回 403/404。路径必须落在LOCAL_FILES_DOCUMENT_ROOT之内是硬性校验。该端点还支持 ETag304 缓存与 HTTP Range 请求因此可以直接用于视频/音频的拖拽播放。使用 HTTPS 运行要以 HTTPS 访问 Web 服务器请使用 NGINX 或其他 Web 服务器为 Label Studio 提供 HTTPS 终结。结合源码可以确认原因label_studio/server.py 中如果检测到--cert或--key参数会打印错误日志并直接退出——Label Studio doesnt support SSL web server with cert and key. Use nginx or other servers for it.因此这两个参数已被废弃正确做法是把 Label Studio 放在 NGINX/其他反向代理之后由代理层处理 TLS 证书。仓库自带的 deploy/nginx/default.conf 与 Docker Compose 中 NGINX 服务docker-compose.yml即展示了这种代理部署形态。在 Heroku 上云端运行要在 Heroku 上运行 Label Studio设置环境变量以让 Label Studio 正常加载LABEL_STUDIO_HOST可以指定不同的主机名但不是必须的。若要使用 PostgreSQL 作为 数据库存储把 PostgreSQL 连接所需的环境变量写入 Heroku 环境变量DATABASE_URL。例如连接 Amazon 托管的 PostgreSQLDATABASE_URL postgres://username:passwordhostname.compute.amazonaws.com:5432/dbname然后按 Database storage 的说明设置 PostgreSQL 连接所需的环境变量。Heroku 清单默认使用 PostgreSQL addon 插件但请注意其存储容量有限。另外需要特别提醒由于 Heroku 的文件系统是临时ephemeral的dyno 重建后所有通过导入上传的数据都会丢失因此强烈建议改用 S3 存储。仓库中的 deploy/heroku_run.sh 与 heroku.yml 即用于支撑 Heroku 部署形态。使用外部域名运行如果希望多人协作可能会想用外部域名运行 Label Studio。方法是启动时使用host参数。该参数保证导入资源文件图片、音频等与生成标注任务时创建正确的 URL。有几种设置外部域名的方式修改--config指定文件中的host参数如果未使用--config则编辑 Label Studio 包目录下label_studio/utils/schema/default_config.json当前仓库对应文件为 label_studio/core/utils/schema/default_config.json其中host: 、internal_host: 0.0.0.0、port: 8080。启动时直接指定label-studio start --host http://your.domain.com/ls-root。设置环境变量尤其在 Docker 场景HOSThttps://your.domain.com:7777。或者使用环境变量LABEL_STUDIO_HOST https://subdomain.example.com:7777注意域名必须带协议前缀http://或https://如果外部主机带端口端口要作为主机名的一部分。从源码看label_studio/core/settings/base.py 读取HOST环境变量并校验其必须以http://或https://开头、且不能以/结尾LABEL_STUDIO_HOST经 label_studio/server.py 落入同一HOST环境变量最终统一用于生成资源链接。为项目设置任务采样启动 Label Studio 时可以控制标注者看到任务的顺序。例如创建任务按顺序展示的项目label-studio start project_name --sampling sequential可用的采样选项如下选项说明sequential默认值。任务按id字段升序展示给标注者。uniform任务以等概率随机采样。prediction-score-min展示平均预测分数最低的任务。使用该选项时导入的任务数据中必须包含 predictions 数据。也可以通过 API 为特定项目设置采样向/api/projects/project_id端点发送 PATCH 请求。详见项目 API 参考。此外单个标注者也可以在 Label Studio 界面中通过调整任务的过滤与排序来控制标注顺序参见 Set up your labeling project。源码视角采样如何落到项目模型采样选项的实现证据在 label_studio/projects/models.pyProject模型定义了三种采样取值——SEQUENCE Sequential sampling、UNIFORM Uniform sampling、UNCERTAINTY Uncertainty sampling对应按数据管理器排序随机选择按模型不确定性分数选择即主动学习模式sampling字段默认SEQUENCE。命令行到模型取值的映射发生在 label_studio/server.pyinit命令路径与 label_studio/server.pystart路径sampling_map { sequential: Project.SEQUENCE, uniform: Project.UNIFORM, prediction-score-min: Project.UNCERTAINTY, }也就是说--sampling prediction-score-min实际启用的是基于模型不确定度的主动学习式任务排序这也是它要求任务数据带 predictions 的原因。【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考