Label Studio 故障排除

安装

参见排查安装问题。

项目

加载项目时出现空白页面

启动Label Studio并打开项目后，您会看到一个空白页面。可能有几个问题导致这种情况。

如果在启动Label Studio时指定了不带协议（如http://或https://）的主机地址，Label Studio可能无法定位正确的文件来加载项目页面。

要解决此问题，请更新在环境变量中指定或在启动Label Studio时设置的主机。参见Start Label Studio。

标注

标注过程中的速度缓慢问题

• 如果您使用的是SQLite数据库，而其他用户导入了大量数据，由于数据库负载增加，服务器上其他用户的标注速度可能会变慢。

• 如需上传大量数据（数千条记录），建议在无人进行标注时操作，或改用其他数据库后端如PostgreSQL或Redis。您可以从Label Studio的根目录运行Docker Compose来使用PostgreSQL：docker-compose up -d，或参阅Sync data from cloud or database storage。

• 如果您使用的标注方案包含数千个标签，请考虑改用外部分类法。

标注过程中图片/音频/资源加载错误

资源加载时最常见的错误是CORS(跨域资源共享)问题或跨域问题。当您尝试从外部托管获取图片时，可能会因安全原因被阻止。

打开浏览器控制台并检查其中的错误。通常，这个问题可以通过外部主机设置解决。

• 如果您以管理员身份拥有托管服务器的访问权限，那么您需要为Web服务器允许CORS。例如，在nginx上，您可以尝试将以下行添加到/etc/nginx/nginx.conf中的location部分下：

location <YOUR_LOCATION> {
     if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
        #
        # Custom headers and headers various browsers *should* be OK with but aren't
        #
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
        #
        # Tell client that this pre-flight info is valid for 20 days
        #
        add_header 'Access-Control-Max-Age' 1728000;
        add_header 'Content-Type' 'text/plain; charset=utf-8';
        add_header 'Content-Length' 0;
        return 204;
     }
     if ($request_method = 'POST') {
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
        add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range';
     }
     if ($request_method = 'GET') {
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
        add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range';
     }
}

• 对于Amazon S3，请参阅Amazon S3用户指南中的配置和使用跨源资源共享(CORS)。
• 关于GCS，请参阅Google Cloud Storage文档中的配置跨源资源共享(CORS)。
• 对于Microsoft Azure，请参阅Microsoft Azure文档中的Azure存储的跨域资源共享(CORS)支持。
• 如果您通过如下方式创建的HTTP服务器提供数据：python -m http.server 8081 -d，请从命令行运行以下命令：

  npm install http-server -g
  http-server -p 3000 --cors

并非所有主机都支持CORS设置，但您可以尝试在主机配置的管理区域中查找CORS设置。

音频波形与标注不匹配

如果您发现在标注音频数据后，显示的音频波形与时间戳及声音不匹配，可以尝试将音频转换为其他格式。例如，如果您正在标注mp3文件，可以尝试将其转换为wav文件。

ffmpeg -y -i audio.mp3 -ar 8k -ac 1 audio.wav

标注者无法看到预测结果

参见下方的预标注部分。

无法标注PDF数据

Label Studio does not support labeling PDF files directly. However, you can convert files to HTML using your PDF viewer or another tool and label the PDF as part of the HTML. See an example labeling configuration in the Label Studio playground.

云端与本地存储

在使用外部云存储连接(S3、GCS、Azure)时，请注意以下几点：

• For Source storage:
  • 当勾选"将每个存储桶对象视为源文件"时，Label Studio不会导入存储桶中的数据，而是创建对这些对象的引用。因此，您可以完全控制要在标注界面上同步和显示的数据访问权限。
  • 当未勾选“将每个存储桶对象视为源文件”时，存储桶文件将被视为不可变；要将更新后的文件状态推送至Label Studio，唯一方法是使用新文件名重新上传，或删除与该文件关联的所有任务并重新同步。
• 与外部存储桶的同步操作是单向的。它要么从存储桶（源存储）中的对象创建任务，要么将标注推送到输出存储桶（目标存储）。更改存储桶端的内容不能保证结果的一致性。
• 我们建议为每个Label Studio项目使用单独的存储桶文件夹。

CORS错误

如果您未设置CORS，则无法从Label Studio查看云存储数据。您可能会看到数据链接而非数据预览，或者在浏览器控制台中看到CORS错误：

• 对于Amazon S3，请参阅Amazon S3用户指南中的配置和使用跨源资源共享(CORS)。
• 关于GCS，请参阅Google Cloud Storage文档中的配置跨源资源共享(CORS)。
• 对于Microsoft Azure，请参阅Microsoft Azure文档中的Azure存储的跨源资源共享(CORS)支持。

403 错误

如果在浏览器控制台中看到403错误，请确保已配置正确的凭据。

点击同步按钮未更新我的数据

有时同步过程不会立即启动。这是因为同步过程基于内部作业调度器。如果一段时间后仍未发生任何变化，请按照以下步骤操作。

首先，请确认您已输入正确的凭据（参见上文相关章节）。

然后前往云存储设置页面，点击云连接旁边的编辑按钮。从这里您可以检查以下内容：

• 文件过滤正则表达式已设置且正确。当未指定过滤器时，所有找到的项目都会被跳过。过滤器应为有效的正则表达式，而非通配符（例如.*有效，*.无效）

• 将每个存储桶对象视为源文件 如果您处理存储在存储桶中的图像、音频、文本文件或任何其他二进制内容，应切换为ON。

  这会指示Label Studio创建URI端点并将其存储为标注任务有效载荷，在打开标注界面时将其解析为预签名的https URL。

  如果您以Label Studio格式在存储桶中存储JSON任务 - 请将此切换设为OFF。

• 检查rq worker是否出现故障。检查rq worker是否正常的一个简单方法是完成导出操作。

  在数据管理器中，点击导出，创建新快照并下载JSON文件。如果看到错误提示，很可能您的rq worker出现了问题。另一种检查rq worker的方法是使用超级用户登录并访问/django-rq页面。您应该能看到workers列。如果该列显示0或为空，则可能表示出现了故障。

来自云存储的JSON文件未同步且数据管理器为空

1. 编辑存储设置以启用将每个存储桶对象视为源文件。如果在数据管理器中看到任务，请继续执行步骤2。

2. 禁用将每个存储桶对象视为源文件选项。

   如果在数据管理器中看不到任务，说明您的存储桶仅具备LIST权限，没有GET权限。

如果仅有LIST权限，Label Studio可以扫描存储桶中对象的存在性而无需实际读取内容。拥有GET权限后，Label Studio便能读取数据并正确解析您的JSON文件。

任务加载不符合预期

如果任务同步到Label Studio但显示方式不符合预期，例如出现URL而非图像，或预期看到多个任务却只显示一个，请检查以下内容：

• 如果您将JSON文件放置在云存储中，请确保同一文件中的多个任务都采用相同的格式（例如，不能在一个文件中同时存在原始data字段内容的任务和包含注释与预测的任务）。
• 如果您正在同步图像或音频文件，请确保将每个存储桶对象视为源文件选项已启用。

在Windows系统下无法访问本地存储

如果您使用的是Windows系统：

1. 在设置环境变量LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT时，请确保使用双反斜杠(\\)。这是必要的，因为您必须对反斜杠()进行转义。
2. 在配置项目的本地存储时，输入绝对本地路径时请确保使用单反斜杠(\)。
3. 不要在LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT或绝对本地路径中使用空格或非拉丁符号。

示例：

LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=c:\\data\\media
Absolute local path from Local Storage settings = c:\data\media\subpath

预标注

请确认您使用的是正确的标注单元。

标注者无法查看预测结果

如果标注人员无法看到预测结果，或者在将预标注导入Label Studio后遇到意外行为，请查阅本指南以解决问题。

首先，在项目的设置 > 标注部分，确保已启用使用预测结果进行预标注任务选项。

检查标注配置和任务的配置值

预标注任务JSON中的from_name必须与标注配置中部分的name值相匹配。to_name必须与toName值一致。

例如，以下XML代码：

...
<Choices name="choice" toName="image" showInLine="true">`
...
<RectangleLabels name="label" toName="image">
...

应与示例JSON的以下部分对应：

...
"type": "rectanglelabels",        
"from_name": "label", "to_name": "image",
...
type": "choices",
"from_name": "choice", "to_name": "image",
...

检查配置和任务中的标签

确保您已为标注界面设置好标注配置，并且JSON文件中的标签与配置中的标签完全匹配。如果您正在使用工具来转换模型输出，请确保该工具不会修改标签。

检查ID和toName值

如果您正在进行嵌套标注，例如为特定的标签或选项值显示文本区域标签，这些结果的ID必须匹配。

例如，如果您想在命名实体识别任务的同时转录文本，您可以使用以下标注配置：

<View>
  <Labels name="label" toName="text">
    <Label value="PER" background="red"/>
    <Label value="ORG" background="darkorange"/>
    <Label value="LOC" background="orange"/>
    <Label value="MISC" background="green"/>
  </Labels>
  <Text name="text" value="$text"/>
  <TextArea name="entity" toName="text" perRegion="true"/>
</View>

如果你想为此标注配置添加预测文本和建议转录内容，可以使用以下示例JSON。

{
"data":{
         "text":"The world that we live in is a broad expanse of nothingness, said the existential philosopher, before he rode away with his cat on his motorbike. "
      },
   "predictions":[
      {
            "result":[
               {
                  "value":{
                     "start":135,
                     "end":144,
                     "text":"motorbike",
                     "labels":[
                        "ORG"
                     ]
                  },
                  "id":"def",
                  "from_name":"ner",
                  "to_name":"text",
                  "type":"labels"
               },
               {
                  "value":{
                     "start":135,
                     "end":144,
                     "text":[
                        "yay"
                     ]
                  },
                  "id":"def",
                  "from_name":"entity",
                  "to_name":"text",
                  "type":"textarea"
               }
            ]
      }
   ]
}

由于TextArea标签适用于每个标注区域，标签结果和文本区域结果的ID必须匹配。

只读和隐藏区域

在某些情况下，隐藏或将边界框、文本片段、音频片段等设置为read-only非常有用。您可以在区域中添加"readonly": true或"hidden": true来实现这一点（位于annotations.result列表中的字典内）。

导出

HTML label offsets are in the wrong places

If the offsets for exported HTML labels don’t match your expected output, such as with HTML named entity recognition (NER) tasks, the most common reason why is due to HTML minification. When you upload HTML files to Label Studio for labeling, the HTML is minified to remove whitespace. When you annotate those tasks, the offsets for the labels apply to the minified version of the HTML, rather than the original unmodified HTML files.

To prevent the HTML files from being minified, you can use a different import method. See Import HTML data for more.

If you want to correct existing annotations, you can minify your source HTML files in the same way that Label Studio does. The minification is performed with the following script:

import htmlmin

with open("sample.html", "r") as f:
html_doc = f.read()

minified_html_doc = htmlmin.minify(html_doc, remove_all_empty_space=True)

如果压缩似乎没有影响偏移位置，可能是复杂CSS或其他原因导致的。

机器学习后端

您可以通过服务器控制台日志来排查大多数问题。机器学习后端作为独立于Label Studio的服务器运行，因此在故障排除时请确保检查正确的服务器控制台日志。如需查看更详细的日志，请使用--debug选项启动ML后端服务器。

如果您正在运行ML后端：

• 生产环境训练日志位于 my_backend/logs/rq.log
• 生产环境运行时日志位于my_backend/logs/uwsgi.log 在开发模式下，训练日志会显示在网页浏览器控制台中。

如果您正在使用Docker Compose运行ML后端：

• 训练日志位于 logs/rq.log
• 主进程和推理日志位于 logs/uwsgi.log

Label Studio 默认的ML服务器请求超时设置

Label studio 对所有类型请求到 ML 服务器的操作都设置了默认超时时间。

Label studio 向机器学习服务器发出几种不同类型的请求：

1. 健康检查 - 在添加新ML后端时请求检查ML后端健康状态（环境变量 ML_TIMEOUT_HEALTH）
2. 设置 - 请求设置ML后端，初始化ML模型（环境变量 ML_TIMEOUT_SETUP）
3. Predict - 当Label Studio从机器学习后端获取预测时的预测请求（环境变量 ML_TIMEOUT_PREDICT）
4. 训练 - 请求训练机器学习后端 (环境变量 ML_TIMEOUT_PREDICT)
5. 复制模型 - 向ML后端发送复制模型请求（环境变量 ML_TIMEOUT_PREDICT）
6. 删除 - 向ML后端发送删除请求（环境变量 ML_TIMEOUT_PREDICT）
7. 训练任务状态 - 从ML后端请求训练任务状态（环境变量 ML_TIMEOUT_PREDICT）

您可以通过为每个请求设置环境变量或在Label Studio变量中修改来调整超时时间。以下是Label Studio中的变量部分（以秒为单位）：

CONNECTION_TIMEOUT = float(get_env('ML_CONNECTION_TIMEOUT', 1))  
TIMEOUT_DEFAULT = float(get_env('ML_TIMEOUT_DEFAULT', 100))  
TIMEOUT_TRAIN = float(get_env('ML_TIMEOUT_TRAIN', 30))
TIMEOUT_PREDICT = float(get_env('ML_TIMEOUT_PREDICT', 100))
TIMEOUT_HEALTH = float(get_env('ML_TIMEOUT_HEALTH', 1))
TIMEOUT_SETUP = float(get_env('ML_TIMEOUT_SETUP', 3))
TIMEOUT_DUPLICATE_MODEL = float(get_env('ML_TIMEOUT_DUPLICATE_MODEL', 1))
TIMEOUT_DELETE = float(get_env('ML_TIMEOUT_DELETE', 1))
TIMEOUT_TRAIN_JOB_STATUS = float(get_env('ML_TIMEOUT_TRAIN_JOB_STATUS', 1))

您可以在ml/api_connector.py中修改它们。

我已启动ML后端，但在Label Studio界面添加后显示为已断开连接

您的机器学习后端服务器可能未正确启动。

1. 检查ML后端服务器是否正在运行。运行以下健康检查：
   curl -X GET http://localhost:9090/health
2. 如果健康检查没有响应，或者您看到错误，请检查服务器日志。
3. 如果您使用Docker Compose启动ML后端，请检查Docker内部环境设置所用的requirements.txt文件中是否缺少依赖项。

ML后端似乎已连接，但当我点击"开始训练"后，看到"错误。点击此处查看详情。"的提示信息

点击错误信息查看回溯详情。您可能会遇到的常见错误包括：

• Insufficient number of annotations completed for training to begin.
• 服务器内存问题。 如果无法自行解决回溯问题，请在Slack上联系我们。

我的预测结果有误或在标注页面看不到模型预测结果

您的机器学习后端可能以错误的格式生成预测结果。

• 检查ML后端预测格式是否与导入的预标注中的预测结构一致。
• 确认您的项目标签配置与机器学习后端生成的输出相匹配。例如，使用标签为文本创建预测类别。查看更多Label Studio标签。

模型后端无法启动或正常运行

如果在启动ML后端服务器后，在终端或日志中看到关于缺失包的报错，您可能需要在ML后端的requirements.txt文件中指定额外的依赖包。

ML后端无法访问任务

由于ML后端和Label Studio是不同的服务，您标注的资产（如图片、音频等）必须托管并通过URL可供机器学习后端访问，否则可能无法生成预测结果。

添加ML后端时出现验证错误

如果在将ML后端URL添加到Label Studio项目时遇到验证错误，请检查以下内容：

• 标注界面是否设置了有效的配置？
• 机器学习后端是否在运行？执行以下健康检查：
  curl -X GET http://localhost:9090/health
• 您的机器学习后端是否可以从您的Label Studio实例访问？它必须对运行Label Studio的实例可用。

如果您在Docker中运行Label Studio，则必须在同一个Docker容器内运行机器学习后端，或者使其对运行Label Studio的Docker容器可用。您可以使用docker exec命令在Docker容器内运行命令，或者使用docker exec -it /bin/sh在容器上下文中启动shell。请参阅docker exec文档。

Windows 上出现“没有这样的文件或目录”错误

如果在Windows上运行docker-compose up --build时遇到类似以下错误：

exec /app/start.sh : No such file or directory
exited with code 1

这个问题很可能是由于Windows系统对文本文件中换行符的处理方式导致的，这会影响像start.sh这样的脚本。要解决此问题，请按照以下步骤操作：

步骤1：调整Git配置

在克隆仓库之前，请确保您的Git配置不会在检出文件时自动将行尾转换为Windows风格(CRLF)。这可以通过将core.autocrlf设置为false来实现。打开Git Bash或您首选的终端并执行以下命令：

git config --global core.autocrlf false

步骤2：再次克隆仓库

如果您在调整Git配置之前已经克隆了仓库，您需要重新克隆以确保换行符正确保留：

1. 删除现有的本地仓库。 确保您已备份所有更改或进行中的工作。
2. 再次克隆仓库。 使用标准的Git克隆命令将仓库克隆到您的本地机器上。

步骤3：构建并运行Docker容器

导航到克隆仓库中包含Dockerfile和docker-compose.yml的相应目录。然后继续执行Docker命令：

1. 构建Docker容器：运行docker-compose build命令，根据docker-compose.yml文件中指定的配置来构建Docker容器。

2. 启动Docker容器： 构建过程完成后，使用docker-compose up命令启动容器。

补充说明

• 此解决方案专门针对Windows系统中因行尾自动转换导致的问题。如果您使用的是其他操作系统，此方案可能不适用。
• 请记得检查您项目的.gitattributes文件（如果存在），因为它也会影响Git如何处理文件中的行尾符。

按照以下步骤操作，您应该能够解决由于行尾转换导致Docker在Windows上无法识别start.sh脚本的问题。

Docker镜像中的Pip缓存重置

有时，您需要重置pip缓存以确保安装依赖项的最新版本。 例如，Label Studio ML Backend库在requirements.txt中被引用为 label-studio-ml @ git+https://github.com/HumanSignal/label-studio-ml-backend.git。假设该库已更新，而您希望在包含ML模型的docker镜像中使用最新版本。

您可以使用以下命令从头开始重建docker镜像：

docker compose build --no-cache

Bad Gateway 和 Service Unavailable 错误

如果您发送多个并发请求，可能会看到这些错误。

请注意，提供的ML后端示例仅适用于开发模式，不支持生产级推理服务。

ML后端无法进行简单的自动标注或无法查看预测结果

您必须确保机器学习后端能够访问您的Label Studio数据。如果无法访问，可能会遇到以下问题：

• no such file or directory 错误出现在服务器日志中。
• 在Label Studio中加载任务时，您无法看到预测结果。
• 您的机器学习后端似乎已正确连接，但似乎无法在任务中完成任何自动标注。

为了解决这个问题，请确保您已设置LABEL_STUDIO_URL和LABEL_STUDIO_API_KEY环境变量。更多信息请参阅允许ML后端访问Label Studio数据。