新手必看！MacBook Pro苹果电脑M系列芯片安装 Label Studio 教程方法大全

新手必看！MacBook Pro苹果电脑M系列芯片安装 Label Studio 教程方法大全

本文将从零开始，面向完全没有相关经验的初学者用户，详细地介绍如何在配备 Apple M 系列芯片的 MacBook Pro 上成功安装并运行 Label Studio。文中所有示例均基于 macOS Ventura 及以上版本如 macOS Monterey、macOS Big Sur 等，并假设你使用的是 M1、M1 Pro、M1 Max、M2 等架构。请务必按顺序阅读，确保每一步操作都能顺利完成。

作者✍️猫头虎 > > 公众号：猫头虎技术团队 > 开发者社群欢迎建联～

1. 什么是 Label Studio？

Label Studio 是一款开源的数据标注与管理平台，支持图像、文本、音频、视频等多种数据类型的可视化标注。它具有以下特点：

• 多种数据类型支持：你可以在同一平台上同时标注图片、视频、音频、文本等。
• 灵活的标注界面：可通过自定义配置（Config）或 JSON 格式定义想要的标注任务界面。
• 导入/导出多种格式：原始数据与标注结果支持 JSON、CSV、COCO、PASCAL VOC、YOLO 等格式，方便与下游任务（如深度学习训练）连接。
• 扩展性强：内置插件系统，支持将标注任务与模型推理结合，自动标注以及后处理脚本。

对于从零开始想要搭建本地标注环境、进行入门学习与练习的同学，Label Studio 是非常友好且功能完善的首选。

作者✍️猫头虎 > 微信号：Libin9iOak > 公众号：猫头虎技术团队 > 开发者社群欢迎建联～

2. 为何在 M 系列芯片上需特别注意？

苹果从 2020 年开始逐步从 Intel x86 架构迁移到自研 Apple Silicon（M1、M2 系列）。MacBook Pro M 系列芯片（如 M1、M1 Pro、M1 Max、M2 等）属于 ARM 架构，这与 x86 存在一定差别：

1. 原生软件兼容性：部分第三方工具或依赖包在 ARM 架构下尚未完全适配，可能会出现编译失败或无法安装的情况。
2. Rosetta 2 翻译层：Apple 提供 Rosetta 2 翻译层，能够在一定程度上让 x86 软件在 M 系列上“如同”原生运行，但性能会稍有损失。
3. Docker 镜像兼容性：很多 Docker 镜像默认是 x86 架构，直接在 M 系列上跑时可能因架构不匹配而无法启动。
4. Python 第三方库：部分使用 C/C++ 扩展的 Python 包（如 numpy、pandas、opencv 等）在编译时，若不指定对应架构，会报错或安装失败。

因此，在 M 系列 MacBook Pro 上安装 Label Studio，需要额外关注环境的架构设定、依赖包的兼容性，以及 Docker 镜像的 ARM 支持。

作者✍️猫头虎 > 微信号：Libin9iOak > 公众号：猫头虎技术团队 > 开发者社群欢迎建联～

3. 准备工作：系统与硬件检查

3.1. 检查 macOS 版本

1. 点击屏幕左上角苹果（）图标，选择 “关于本机”（About This Mac）。
2. 确认操作系统版本号（例如：macOS Ventura 13.4、macOS Monterey 12.7、macOS Big Sur 11.7 等）。
3. 建议尽量保持系统为最新版本，以确保 Homebrew、Rosetta 2 等工具的顺利安装。

# 在终端执行以下命令，也能查看 macOS 版本
sw_vers

如果你的 macOS 版本低于 11.0（Big Sur），请先升级系统。

3.2. 检查 Apple M 系列芯片型号

在 “关于本机” 中可看到 “处理器” 一项。如果看到 “Apple M1”、“Apple M1 Pro”、“Apple M2” 等，即说明你的电脑为 M 系列芯片。

# 也可以在终端执行：
uname -m
# 如果输出 arm64，则说明你的机器为 ARM 架构。

3.3. 安装 Rosetta 2（可选，但强烈推荐）

Rosetta 2 是苹果提供的 x86 翻译层，能够让你在 M 系列 Mac 上运行尚未适配 ARM 的软件。安装后，对于部分依赖包或命令会更顺利。严重依赖 x86 架构的软件，如某些 Docker 镜像，推荐先启用 Rosetta 2。

# 打开终端，执行以下命令以检查是否已安装 Rosetta 2：
/usr/bin/pgrep oahd

# 如果返回空行，说明尚未安装；可以执行：
softwareupdate --install-rosetta --agree-to-license

安装 Rosetta 2 需要管理员权限，执行上述命令时会提示输入密码，按提示操作即可。

4. 安装基础工具

4.1. 安装 Homebrew（macOS 包管理器）

Homebrew 是 macOS 最常用的包管理器，可以用来安装 python3、git、wget 等多种常用工具。安装步骤如下：

打开“终端”（Terminal）。

复制以下命令并粘贴到终端，按回车执行：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

在安装过程中，若出现提示 “Press RETURN to continue or any other key to abort”，按回车即可。

安装完成后，按照终端提示，将 /opt/homebrew/bin 添加到 PATH。例如（假设使用 zsh）：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
source ~/.zprofile

验证 Homebrew 是否安装成功：

brew --version
# 正常情况下会输出类似：Homebrew 4.0.0

如果网络较慢，可考虑使用国内镜像源（例如中科大、清华），可参照 Homebrew 官网文档。

4.2. 安装 Python3 环境

macOS 自带 Python2（已逐步弃用）和 Python3，但建议使用 Homebrew 安装或升级到最新 Python3 版本，并且通过 pyenv 或者系统自带的虚拟环境管理工具来隔离项目依赖，避免冲突。

4.2.1. 安装 pyenv（可选，但推荐）

pyenv 可以方便地管理多个 Python 版本。如果你只是做一个项目，也可以直接使用系统 Python3。这里推荐安装 pyenv：

brew install pyenv

配置 pyenv（以 zsh 为例，将以下内容添加到 ~/.zshrc）：

# pyenv 初始化
if command -v pyenv 1>/dev/null 2>&1; then
  eval "$(pyenv init --path)"
fi

重启终端或者执行 source ~/.zshrc 之后，安装 Python3.10（示例）：

pyenv install 3.10.12
pyenv global 3.10.12

查看 Python 版本是否切换成功：

python3 --version
# 应该输出：Python 3.10.12

注意：如果你不熟悉 pyenv，也可以直接使用 Homebrew 安装 Python3：

brew install python
python3 --version

4.2.2. 安装必要的依赖库

Label Studio 依赖 Git、pip、node（可选扩展时用到）等工具。这里建议一并安装常见开发工具。

# 安装 Git
brew install git

# 安装 pipenv（可选，用于虚拟环境管理，更简单）
brew install pipenv

# （可选）安装 Node.js，如果你需要对前端模板进行定制或构建
brew install node

初学者可先只安装 git 与 python3，待后续需要时再安装 node。

4.3. 配置 virtualenv（虚拟环境）

为了防止与系统自带的 Python 环境相冲突，推荐在项目目录下创建一个隔离的虚拟环境。可以使用 python3 -m venv、pipenv 或 virtualenv。这里以 python3 -m venv 为例：

进入一个你自己创建的项目文件夹，比如 ~/projects/label_studio_demo：

mkdir -p ~/projects/label_studio_demo
cd ~/projects/label_studio_demo

创建并激活虚拟环境：

python3 -m venv venv
source venv/bin/activate

成功后，你会看到终端提示符前出现 (venv)，表示当前已在该虚拟环境中。

更新 pip 及 setuptools：

pip install --upgrade pip setuptools

如果你使用 pipenv，则可以直接在项目目录执行：

pipenv --python 3.10
pipenv shell

5. 安装 Label Studio

5.1. 使用 pip 安装（推荐）

5.1.1. 安装步骤

确保当前处于 激活的虚拟环境 中（可通过 which python 检查，路径应指向 ~/projects/label_studio_demo/venv/...）。

直接使用 pip 安装最新版 Label Studio：

pip install label-studio

安装过程会自动下载 Label Studio 核心包与其依赖，包括 Django、Django REST framework、Pillow、numpy 等。

安装完成后，验证安装：

label-studio --version
# 应该输出类似：label-studio, version 1.x.x

注意：由于 M 系列架构为 ARM，如果在安装过程中出现某些依赖包编译失败的错误（比如 psycopg2、opencv-python 等），可以尝试使用 Homebrew 提供的依赖库，或者加上环境变量。

例如，如果 Pillow 安装失败，可以先安装系统库：

brew install libjpeg libpng libtiff
export LDFLAGS="-L/opt/homebrew/lib"
export CPPFLAGS="-I/opt/homebrew/include"
pip install Pillow

5.1.2. 创建项目目录并初始化

在该虚拟环境下，初始化 Label Studio 项目（此命令会在当前目录生成一个默认的 label_studio 配置文件夹，用于存放数据库等）：

label-studio init

执行后，你会看到如下信息：

Creating project directory:
/Users/yourname/projects/label_studio_demo/label_studio_data
Success!

进入生成的 label_studio_data 目录，可以看到其中包含：

• db.sqlite3：SQLite 数据库文件，用于存储标注任务、用户信息等。
• media/：存放上传的原始数据及标注结果图像等。
• config/、static/、templates/：Label Studio 的后台配置、前端静态文件、HTML 模板等。

如果希望使用 MySQL、PostgreSQL 或其他数据库，请在初始化前先配置相应环境变量，详见 Label Studio 官方文档。

5.2. 使用 Docker 安装（进阶用户可选）

如果你熟悉 Docker，并且希望将 Label Studio 运行在容器中以便于部署和隔离环境，也可以选择使用 Docker。由于 M 系列搭载 ARM 芯片，需注意使用到的 Docker 镜像是否支持 arm64 架构。

5.2.1. 安装 Docker Desktop for Mac

前往 Docker 官方网站 下载 Docker Desktop for Mac (Apple Silicon) 版本。

按照提示安装并启动 Docker。首次运行时，会提示获取访问权限，点击确认即可。

安装完成后，在终端执行以下命令，确认 Docker 已就绪：

docker info

其中若看到 Architecture: aarch64，说明 Docker 已识别为 ARM 架构，后续使用 ARM 镜像更佳。

5.2.2. 拉取并运行 Label Studio 官方镜像

到目前为止，Label Studio 官方并未提供专门的 arm64 镜像版本，大多数镜像基于 python:3.8-slim-buster (x86_64)。若直接拉取 labelstudio/label-studio:latest，在 M 系列上可能会因为架构不匹配而失败。

解决方案一：使用 --platform linux/amd64 强制以 x86 架构跑（需依赖 Rosetta 2）

docker pull --platform linux/amd64 heartexlabs/label-studio:latest
docker run --platform linux/amd64 -it \
  -p 8080:8080 \
  -v ~/projects/label_studio_data_docker:/label-studio/data \
  heartexlabs/label-studio:latest

• —platform linux/amd64 强行拉取 x86 镜像并在 M1 上通过 Rosetta 2 转译运行
• -p 8080:8080 将容器 8080 端口映射到本机 8080
• -v ...:/label-studio/data 将本机数据文件夹挂载到容器内，方便持久化

解决方案二：自行构建 ARM 镜像

在本地新建一个 Dockerfile，并指定基础镜像为 python:3.10-slim（ARM 支持较好）：

FROM python:3.10-slim
WORKDIR /app
# 安装 Label Studio 及其依赖
RUN pip install --upgrade pip && \
    pip install label-studio
# 暴露 8080 端口
EXPOSE 8080
# 设置环境变量
ENV LABEL_STUDIO_HOME=/label-studio-data
# 挂载卷时若数据目录不存在则创建
RUN mkdir -p $LABEL_STUDIO_HOME
VOLUME ["$LABEL_STUDIO_HOME"]
# 默认启动命令
CMD ["label-studio", "start", "--host", "0.0.0.0", "--port", "8080"]

在该 Dockerfile 所在目录执行（假设目录为 ~/projects/label_studio_docker）：

cd ~/projects/label_studio_docker
docker build -t label-studio-arm .

等待构建完成后，运行：

docker run -it \
  -p 8080:8080 \
  -v ~/projects/label_studio_data_docker:/label-studio-data \
  label-studio-arm

等待容器启动后，访问 http://localhost:8080 即可进入 Label Studio 界面。

使用 Docker 需要保证机子有一定内存（至少 4GB），否则容器容易因内存不足而崩溃。

注意：无论是强制 x86 架构运行（解决方案一），还是自行构建 ARM 镜像（解决方案二），都要确保所挂载的本地目录有读写权限，否则可能出现无法写入数据、无法保存标注结果等问题。

作者✍️猫头虎 > 微信号：Libin9iOak > 公众号：猫头虎技术团队 > 开发者社群欢迎建联～

6. 第一次启动与配置

6.1. 启动 Label Studio

6.1.1. 使用 pip 安装方式启动

在激活了虚拟环境、并完成 label-studio init 后，只需在项目根目录（包含 label_studio_data 文件夹）执行：

cd ~/projects/label_studio_demo
label-studio start

默认会在后台启动一个服务，监听 localhost:8080。

终端中会输出日志，例如：

Starting Label Studio at: http://localhost:8080

若想指定自定义端口（例如 9000），可执行：

label-studio start --port 9000

6.1.2. 使用 Docker 安装方式启动

若使用 Docker 容器，则默认命令已在镜像中配置。如使用解决方案一（x86 镜像），启动命令示例：

docker run --platform linux/amd64 -it \
  -p 8080:8080 \
  -v ~/projects/label_studio_data_docker:/label-studio/data \
  heartexlabs/label-studio:latest

若使用解决方案二（自行构建 ARM 镜像）：

docker run -it \
  -p 8080:8080 \
  -v ~/projects/label_studio_data_docker:/label-studio-data \
  label-studio-arm

启动后，若觉得容器窗口日志刷得过快，可以添加 -d 参数让容器在后台运行：

docker run -d --name label-studio-arm \
  -p 8080:8080 \
  -v ~/projects/label_studio_data_docker:/label-studio-data \
  label-studio-arm

6.2. 登录与创建第一个项目

1. 在浏览器中打开：http://localhost:8080
2. 首次访问会出现 注册管理员账号 界面，填写用户名（如 admin）、邮箱、密码等信息。
3. 提交后会自动登录并进入 Dashboard（仪表盘）。
4. 点击 “Create Project” 或 “New Project” 按钮，按照向导填写项目名称与描述，比如 “我的第一个标注项目”。
5. 在标注界面配置阶段，可选择 Label Studio 提供的默认模板，或自行编写自定义 JSON Config。建议初学者先使用默认模板。
6. 完成项目创建后，上传待标注的数据（如图片或文本），便可开始标注操作。
   • 上传本地文件：可通过 “Upload” 按钮，选择本地图像/JSON/文本等。
   • 远程数据链接：支持从 S3、Google Cloud、HTTP/FTP 等 URL 拉取数据。
7. 点击 “Start Labeling” 进入任务列表，便可开始第一条数据的标注。每次标注完成后，点击 “Submit” 保存结果。

如果你想直接导入 COCO、VOC、CSV 等常见格式，可在项目设置中选择 “Import” 并指定对应文件夹或路径。

作者✍️猫头虎 > 微信号：Libin9iOak > 公众号：猫头虎技术团队 > 开发者社群欢迎建联～

7. 常见问题与解决方案

7.1. “无法找到 Python 解释器”

症状：终端执行 label-studio start 后，提示 command not found: label-studio，或者 No module named label_studio。

原因：可能没有进入正确的虚拟环境，或全局 PATH 没有包含 Python 包路径。

解决方法：

确认当前激活虚拟环境：终端提示符有 (venv)；

执行 which label-studio，应输出类似 ~/projects/label_studio_demo/venv/bin/label-studio；

如果没有，尝试重新安装：

pip install --upgrade label-studio

若依旧找不到，请检查 pip3 install --user label-studio 是否被误执行，将全局与局部环境混淆。

7.2. “依赖包编译失败”

症状：在执行 pip install label-studio 过程中，某些包编译报错，如 Pillow、psycopg2、mysqlclient、opencv-python 等。

原因：M 系列芯片需要使用 ARM 对应的 C/C++ 编译工具链，或者系统缺少相关库（如 libjpeg、zlib、freetype）。

解决方法：

确保已安装 Xcode Command Line Tools：

xcode-select --install

使用 Homebrew 安装常见依赖库：

brew install libjpeg libpng freetype zlib

设置环境变量，让编译器能找到这些库：

export LDFLAGS="-L/opt/homebrew/lib"
export CPPFLAGS="-I/opt/homebrew/include"

对于特定包（例如 psycopg2），建议先安装数据库客户端库：

brew install postgresql
pip install psycopg2-binary

重新执行安装：

pip install label-studio

7.3. “使用 Docker 时出现架构不兼容”

症状：拉取镜像后执行 docker run，提示类似 exec format error 或 no matching manifest for linux/arm64/v8 in the manifest list。

原因：默认镜像为 x86 架构，M 系列需指定 --platform 或者改用 ARM 架构镜像。

解决方法：

强制拉取 x86 镜像（依赖 Rosetta 2）：

docker pull --platform linux/amd64 heartexlabs/label-studio:latest

自行构建 ARM 镜像：

• 如前文第 5.2.2 节所示，自行写一个 Dockerfile 并 base image 指向 python:3.10-slim（arm64 版本）。

使用第三方社区提供的 ARM 镜像（需自行搜索、验证安全性）。

7.4. “端口冲突导致无法启动”

症状：执行 label-studio start 后，提示 Address already in use: 8080。

原因：本机的 8080 端口已被其他程序占用。

解决方法：

查看占用 8080 端口的进程：

lsof -i :8080

如果不需要该进程，可使用 kill <PID> 终止。

或者在启动时指定其他端口，例如：

label-studio start --port 9000

如果 Docker 容器映射冲突，可修改映射为其它端口，如 -p 9000:8080。

作者✍️猫头虎 > 微信号：Libin9iOak > 公众号：猫头虎技术团队 > 开发者社群欢迎建联～

8. 实用插件与扩展

8.1. Label Studio SDK 简介

Label Studio 提供了 Python SDK，用于通过脚本化方式管理项目、导入数据、导出标注结果，甚至可将模型接入，实现自动标注。安装 SDK 方法如下：

pip install label-studio-sdk

SDK 常见用法示例

下面给出一个简单的示例，用于创建项目并批量导入图像数据：

from label_studio_sdk import Client

# 连接到本地运行的 Label Studio 实例
ls = Client(url="http://localhost:8080", api_key="YOUR_API_KEY_HERE")

# 创建一个新项目
project = ls.start_project(
    title="SDK 示例项目",
    label_config="""
    <View>
      <Image name="img" value="$image" />
      <Choices name="label" toName="img">
        <Choice value="Cat" />
        <Choice value="Dog" />
      </Choices>
    </View>
    """
)

# 准备要导入的标签数据列表
tasks = [
    {"data": {"image": "https://example.com/dog1.jpg"}},
    {"data": {"image": "https://example.com/cat1.jpg"}}
]

# 批量导入任务
project.import_tasks(tasks)
print("任务已导入，共 %d 条" % len(tasks))

• 你需要先在 Web 界面获取 api_key，在 Account Settings -> API Tokens 中创建一个新 Token。
• label_config 部分为 XML 格式，定义了标注界面。更多自定义配置可参考官方文档。

8.2. 与云存储（AWS S3、Google Cloud）集成

如果你的数据托管在 AWS S3 或 Google Cloud Storage，Label Studio 支持直接从云端拉取数据，无需手动下载。

AWS S3 示例

1. 在 AWS 控制台创建一个 IAM 用户，分配对指定 S3 Bucket 的读写权限。
2. 获取 Access Key ID、Secret Access Key 以及 Bucket 名称。
3. 在 Label Studio 项目配置页面，选择 “Data Import -> Amazon S3” 选项，按提示填写：
   • Bucket Name：例如 my-label-data-bucket
   • Access Key：YOUR_AWS_ACCESS_KEY_ID
   • Secret Key：YOUR_AWS_SECRET_ACCESS_KEY
   • Prefix（可选）：例如 images/train/
4. 完成配置后，点击 “Fetch” 会列出该路径下的文件，勾选后即可批量导入。

Google Cloud Storage 示例

1. 在 Google Cloud Console 创建 Service Account，授予相应存储权限。下载 JSON 格式的服务账号密钥文件。
2. 安装并配置 gsutil（可选，也可通过浏览器直接上传）。
3. 在 Label Studio 项目页面，选择 “Data Import -> Google Cloud Storage” 选项，上传 Service Account JSON 文件，并填写 Bucket 名称及 Prefix。
4. 点击 “Fetch” 导入数据。

云存储集成可以极大简化数据管理，当你的数据量较大或分散在云端时，务必尝试此功能。

作者✍️猫头虎 > 微信号：Libin9iOak > 公众号：猫头虎技术团队 > 开发者社群欢迎建联～

9. 性能优化建议

对初学者来说，上述安装完成并顺利运行后可以先体验基本功能，不过在正式项目中，建议对性能进行一定的优化。

9.1. 给 Python 申请更多内存

Label Studio 在处理大规模图像或长文本时，会消耗较多内存。可以通过以下方法优化：

如果使用 SQLite（默认），在单机环境下可无需改动。若数据量 > 10k 条，建议切换到 PostgreSQL 或 MySQL。

在启动时为 Python 进程分配更多内存，例如调整 ulimit：

# 查看当前内存限制
ulimit -a | grep "max memory"
# 如果需要可提升：
ulimit -m unlimited

避免一次性加载过大列表，例如在 SDK 批量导入时，分批次导入（例如每次 500 条）。

9.2. 减少前端冗余配置

1. Label Studio 前端默认加载所有 JavaScript 模块，若你不需要某些高级功能，可在自定义模板中剔除不必要的组件。
2. 在项目配置的 “Label Config” 中，尽量简化配置，仅保留需要的标签类型与任务控件。否则浏览器渲染会变慢。

9.3. 定期清理缓存与数据库

前往 Label Studio 安装目录下的 media/，定期删除不再使用的原始图像、标注结果文件，以节省磁盘空间。

如果使用 SQLite，可使用 VACUUM 操作压缩数据库文件：

sqlite3 db.sqlite3 "VACUUM;"

对于 Docker 用户，可定期运行以下命令，清理未使用的镜像与容器：

# 停止并移除未使用的容器
docker container prune -f
# 删除未使用的镜像
docker image prune -a -f
# 删除未使用的卷
docker volume prune -f

养成定期清理的习惯，能让本地电脑始终保持良好性能。

10. 总结与后续阅读

本文从最基础的环境检查开始，依次介绍了在 Apple M 系列芯片的 MacBook Pro 上安装 Label Studio 的全部细节：

1. 为什么 M 系列需要注意架构差异；
2. 如何安装 Homebrew、Python3、配置虚拟环境；
3. 使用 pip 与 Docker 两种方式安装 Label Studio，分别给出了详细步骤和注意事项；
4. 第一次启动、登录、创建项目、导入数据的完整流程；
5. 常见问题与对应解决方案；
6. Label Studio SDK 批量管理与云存储集成方法；
7. 性能优化与日常维护建议。

对于初学者用户，只要按部就班，基本不需要担心步骤遗漏或环境冲突。后续可以根据业务需求逐步深入：

• 学习编写更复杂的 Label Config，例如：分段标注、复选框、多级关系等。
• 尝试用 Label Studio SDK 编写自动标注脚本，将深度学习模型与标注流程融合。
• 部署到云服务器（如 AWS EC2、阿里云 ECS 等），实现团队协同标注。
• 研究 Label Studio 的插件机制，为项目添加自定义功能。

作者✍️猫头虎 > > 公众号：猫头虎技术团队 > 开发者社群欢迎建联～