# label_studio_note

**Repository Path**: allenchennn/label_studio_note

## Basic Information

- **Project Name**: label_studio_note
- **Description**: label_studio笔记
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-24
- **Last Updated**: 2025-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: labelstudio, Python

## README

# Label studio 本地源码安装

## 一、项目介绍

Label Studio是一个开源的标注平台，有如下特点：

- **多功能**：支持文本、音频、视频、图像等多种类型的标注任务。
- **可扩展性**：支持自定义标注模板，方便适配不同的数据标注需求。
- **协作能力**：支持多人协作，可以方便地管理和分配标注任务。
- **开放源代码**：作为开源项目，Label Studio 可以被自由使用、修改和分发。

本笔记主要是记录本人在windows环境、docker desktop下安装 Label Studio 的源码，将踩过的坑总结记录下来，帮助快速搭建本地数据标注环境。

工作环境：

> windows11
>
> anaconda==>用于创建虚拟环境便于维护
>
> docker desktop
>
> 理解前后端操作命令
>
> pycharm

其他详情见官网：[Label Studio 文档 — Label Studio 概述](https://labelstud.io/guide/get_started)

备注：如果打不开请用魔法。

## 二、源码安装

### 1、项目克隆拉取

拉取官网的代码，地址：[HumanSignal/label-studio：Label Studio 是一种多类型数据标注和注释工具，具有标准化的输出格式](https://github.com/HumanSignal/label-studio/?tab=readme-ov-file#install-locally-with-anaconda)

```
git clone git@github.com:HumanSignal/label-studio.git
```

克隆成功：

```
$ git clone git@github.com:HumanSignal/label-studio.git
Cloning into 'label-studio'...
remote: Enumerating objects: 134095, done.
remote: Counting objects: 100% (1973/1973), done.
remote: Compressing objects: 100% (1039/1039), done.
remote: Total 134095 (delta 1583), reused 979 (delta 933), pack-reused 132122 (from 5)
Receiving objects: 100% (134095/134095), 2.61 GiB | 1.90 MiB/s, done.
Resolving deltas: 100% (89258/89258), done.
Updating files: 100% (4369/4369), done.
```

### 2、创建虚拟环境

```
conda create -n label-studio-source python=3.10
# 激活创建的虚拟环境
conda activate label-studio-source
```

### 3、安装相关依赖

详情见官网：

```
cd label-studio
pip install poetry
poetry install
#需要等待一段时间
# run db migrations
poetry run python label_studio/manage.py migrate

# 搜集静态文件
poetry run python label_studio/manage.py collectstatic

# start the server in development mode at http://localhost:8080
# 开发模型启动服务器http://localhost:8080
poetry run python label_studio/manage.py runserver
```

### 4、问题解决

本地源码安装成功后，启动，但是发现前端页面登录按钮样式有问题：

![image-20250619180012748](assets/image-20250619180012748.png)

并且F12浏览器后端报错：

![Snipaste_2025-06-19_16-24-18](assets/Snipaste_2025-06-19_16-24-18.png)

显示一些静态资源 400 错误，并且 MIME type 不正确（text/html），无法加载和执行，这类问题可能有以下几个原因：

- 前端资源未构建或未正确生成

访问的 /react-app/main.js 等文件是前端构建产物，如果没有先构建前端，后端找不到这些文件，就会返回 400 或 404，甚至返回 HTML 错误页（MIME type 就成了 text/html），

因此也要构建前端：

1）进入web文件夹内

```
(label-studio-source) PS D:\v_desktop\Annotation_platform\label-studio> cd web
```

web项目架构：

![image-20250619180301425](assets/image-20250619180301425.png)

2）安装web端相关依赖

```
# npm install --legacy-peer-deps
(label-studio-source) PS D:\v_desktop\Annotation_platform\label-studio\web> npm install --legacy-peer-deps
```

备注：一些直接的npm install可能出现依赖冲突，所以使用 `--legacy-peer-deps` 参数

> --legacy-peer-deps：忽略 peer 依赖的版本冲突，并安装当前项目中所有的依赖，相当于绕过依赖冲突，继续安装所有依赖。

安装成功：

![image-20250620083804489](assets/image-20250620083804489.png)

3）web目录构建前端产物

```
# npm run build
(label-studio-source) PS D:\v_desktop\Annotation_platform\label-studio\web> npm run build
```

有时候会报错：

```
(label-studio-source) D:\v_desktop\Annotation_platform\test\label-studio\web>npm run build

> @humansignal/source@0.0.0 build
> NODE_ENV=production yarn ls:build

'NODE_ENV' 不是内部或外部命令，也不是可运行的程序
或批处理文件。
```

安装yarn并自动设置好环境变量，兼容 Windows：

```
#全局安装yarn
npm install -g yarn
# yarn
yarn ls:build
```

`yarn ls:build`会查找 `package.json` 中的 `scripts` 部分，执行定义的 `ls:build` 脚本：

![image-20250620091502226](assets/image-20250620091502226.png)

### 5、启动

重新启动本地源码命令

```
# 退回web目录，重新启动服务器
# 开发模型启动服务器http://localhost:8080
poetry run python label_studio/manage.py runserver
```

启动成功：

![image-20250619174608285](assets/image-20250619174608285.png)

## 三、Label Studio ML 后端（Yolo为例）

### 1、简介

`Label Studio ML` 后端是一个 SDK，包装机器学习代码并将其转换为 Web 服务器。 

Web 服务器可以连接到正在运行的 [Label Studio](https://labelstud.io/) 实例，以自动执行标记任务。

详情见官网[HumanSignal/label-studio-ml-backend: Configs and boilerplates for Label Studio's Machine Learning backend](https://github.com/HumanSignal/label-studio-ml-backend?tab=readme-ov-file#)

### 2、项目克隆拉取

```
git clone https://github.com/HumanSignal/label-studio-ml-backend.git
```

![image-20250619102758480](assets/image-20250619102758480.png)

### 3、创建虚拟环境

```
conda create -n label-studio-ml python=3.9
# 激活创建的虚拟环境
conda activate label-studio-ml
```

### 4、设置环境变量和更改参数

**备注：本地部署了“docker desktop”，所以可用docker-compose测试。**

查询`docker-compose.yml`中的`LABEL_STUDIO_HOST`、`LABEL_STUDIO_API_KEY`，需要指定ml需要访问的label studio的URL地址和API密钥。

**原理：**在利用ml算法或模型进行预标注时，ml运行的模型也需要连接label-studio端的一些文档或图像，才能进行预测。如果你都不允许人家连接，人家怎么给你预测对吧？

**注意：**

**LABEL_STUDIO_HOST**

> 1）如果是`windows`本地创建虚拟环境pip安装的label studio，不能使用“`localhost`”或“`127.0.0.1`”，因为其在Docker容器中不起作用，使用`cmd`命令`ipconfig`查看本地电脑的实际`IPv4` 地址。如果是`linux系统`则用`ifconfig`。
>
> 如我本地运行的label studio的地址是`http://localhost:8080/`，我查到的`IPv4地址`为`192.168.0.104`。
>
> 2）如果也是用docker运行的label-studio，同时用docker运行的label-studio-ml，那么LABEL_STUDIO_HOST可以为`http://host.docker.internal:<label-studio-port>`

**LABEL_STUDIO_API_KEY**

> 1）`LABEL_STUDIO_API_KEY` 同样需要设置，否则后端服务无法和 Label Studio 通信，在`label-studio`的**个人账户与设置**中，复制`Access Token`替换即可。
>
> 2）或者将LABEL_STUDIO_API_KEY 设置为本地windows或者linux的环境变量，在docker运行时会自动读取。
>
> ```
> $env:LABEL_STUDIO_API_KEY="你的API密钥"
> $env:LABEL_STUDIO_API_KEY="8c6c934a552039e19af586ef69f19cd792038b58"
> #设置后查看特定的环境变量是否成功
> $Env:LABEL_STUDIO_API_KEY
> # 进入yolo文件夹
> (base) PS D:\v_desktop\Annotation_platform\label-studio-ml-backend> cd .\label_studio_ml\examples\yolo\
> ```

**docker-compose.ym**l

```
      - LABEL_STUDIO_HOST=http://192.168.0.104:8080
      - LABEL_STUDIO_ACCESS_TOKEN=8c6c934a552039e19af586ef69f19cd792038b58
```

![image-20250624161247080](assets/image-20250624161247080.png)

**Dockerfile**

由于直接启动yolo服务可能会报如下问题：

```
exec /app/start.sh: no such file or directory
```

参考其他示例将该文件下的最后一行修改，即：

```
# 删除
CMD [“/app/start.sh”]
# 替换
CMD gunicorn --bind :${PORT:-9090} --workers $WORKERS --threads $THREADS --timeout 0 _wsgi:app
```

### 5、启动服务

在终端启动服务

```
# 启动服务
# 备注：在启动服务之前，先构建所有的 Docker 镜像，然后启动这些服务
(base) PS D:\v_desktop\Annotation_platform\label-studio-ml-backend\label_studio_ml\examples\yolo> docker-compose up --build
```

等待构建，出现如下说明运行成功：

![image-20250624162259477](assets/image-20250624162259477.png)

### 6、服务测试

1）网址测试

将服务启动成功的地址在本地浏览器中输入`http://0.0.0.0:9090/`，得如下结果：

```
{"model_class":"YOLO","status":"UP"}
```

2）label-studio测试

在label-studio中的项目设置中的model==>连接模型![image-20250624162722912](assets/image-20250624162722912.png)

如果连接成功则显示：

![image-20250624162751046](assets/image-20250624162751046.png)

在标签接口中配置标签模板：

![image-20250624162911058](assets/image-20250624162911058.png)

```
<View>
  <Image name="image" value="$image"/>
  <RectangleLabels name="label" toName="image" model_score_threshold="0.25" opacity="0.1">
    <Label value="Person" background="red"/>
    <Label value="Car" background="blue"/>
  </RectangleLabels>
</View>
```

这还不算完全测试成功，导入图片测试一下是否成功，因为有时候ml机器学习后端会有连接拒绝的错误`Connection refused`，如果有那就需要检查`docker-compose.yml`中的`LABEL_STUDIO_HOST`。测试成功如下：

![image-20250624163528924](assets/image-20250624163528924.png)