LocateAnything Linux 部署操作记录

适用场景：Linux GPU 服务器不能直接访问 GitHub / Hugging Face，但可以访问清华镜像或允许从其他机器上传代码和模型。

本记录根据一次实际部署整理：Kylin Linux Advanced Server V10、NVIDIA RTX 4090（23GB 显存）、NVIDIA Driver 580.105.08、CUDA 13.0、Conda 环境、代码和模型离线传输到 /opt/proj。

模型代码位于 NVIDIA NVlabs/Eagle 仓库的 Embodied/ 目录；LocateAnything 的官方安装方式是进入该目录并执行 pip install -e .。官方 Worker API 包含检测、短语定位、文字检测、GUI 定位和点定位。

1. 目录规划

建议统一使用以下目录，后续不要混用 /root/proj 与 /opt/proj：

text 复制代码

/opt/proj/
├── Eagle-main/                 # NVlabs/Eagle 源码解压目录
│   └── Embodied/               # LocateAnything 代码根目录
│       ├── locateanything_worker.py
│       └── run_locateanything.py
├── LocateAnything-3B/          # 本地模型权重目录
└── test_images/                # 输入和输出图像目录

创建目录：

bash 复制代码

mkdir -p /opt/proj/test_images

2. 前置检查：GPU、驱动与系统

bash 复制代码

nvidia-smi
cat /etc/os-release

确认项：

nvidia-smi 能正确显示 GPU、Driver Version 和 CUDA Version。
运行期至少应有一张 NVIDIA GPU 可用。
RTX 4090 只有约 23GB 可用显存；原图分辨率太高时会发生 CUDA OOM，因此本手册后面的推理脚本会自动缩放图片。

检查 GPU 是否被其他进程占用：

bash 复制代码

nvidia-smi

若有无关 Python 进程占用显存，先确认用途后再终止：

bash 复制代码

kill <PID>

3. 创建 Conda 环境

此服务器无法访问 Conda 官方源，但可以访问清华镜像。为避免 Conda 继续请求 defaults，创建环境时直接覆盖 channels：

bash 复制代码

conda create -n locateanything python=3.10 -y --override-channels \
  -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main \
  -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r

激活并确认：

bash 复制代码

conda activate locateanything
python --version
which python

预期示例：

text 复制代码

Python 3.10.x
/.../anaconda3/envs/locateanything/bin/python

4. 安装系统工具

Kylin V10 可用 dnf / yum。若需在服务器端处理压缩包或仓库，安装：

bash 复制代码

dnf install -y git unzip

确认：

bash 复制代码

git --version
unzip -v | head

即使服务器无法访问 GitHub，仍建议安装 git，便于后续维护本地代码或处理其他来源。

5. 获取 Eagle / LocateAnything 源代码

方案 A：服务器能访问 GitHub

bash 复制代码

cd /opt/proj
git clone https://github.com/NVlabs/Eagle.git Eagle

然后使用：

text 复制代码

/opt/proj/Eagle/Embodied

方案 B：服务器不能访问 GitHub（本次采用）

在可访问 GitHub 的电脑下载：

bash 复制代码

wget -O Eagle-main.zip \
  https://github.com/NVlabs/Eagle/archive/refs/heads/main.zip

将 Eagle-main.zip 上传到服务器 /opt/proj/，然后在服务器执行：

bash 复制代码

cd /opt/proj
unzip Eagle-main.zip
ls -lh Eagle-main/Embodied

应可看到：

text 复制代码

locateanything_worker.py
pyproject.toml
README.md
eaglevl/

6. 安装 LocateAnything Python 依赖

进入代码目录：

bash 复制代码

conda activate locateanything
cd /opt/proj/Eagle-main/Embodied

先确认 pip 能通过清华镜像安装：

bash 复制代码

python -m pip install -U wheel \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --trusted-host pypi.tuna.tsinghua.edu.cn

安装项目和依赖：

bash 复制代码

python -m pip install -e . \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --trusted-host pypi.tuna.tsinghua.edu.cn

验证 CUDA 是否能被 PyTorch 使用：

bash 复制代码

python - <<'PY'
import torch
print("torch:", torch.__version__)
print("cuda available:", torch.cuda.is_available())
print("gpu:", torch.cuda.get_device_name(0) if torch.cuda.is_available() else "N/A")
PY

应看到：

text 复制代码

cuda available: True
gpu: NVIDIA GeForce RTX 4090

7. 获取 LocateAnything-3B 模型权重

官方模型名：

text 复制代码

nvidia/LocateAnything-3B

方案 A：服务器能访问 Hugging Face

bash 复制代码

python -m pip install -U "huggingface_hub[cli]"
hf download nvidia/LocateAnything-3B \
  --local-dir /opt/proj/LocateAnything-3B

方案 B：服务器不能访问 Hugging Face（本次采用）

在可访问 Hugging Face 的电脑执行：

bash 复制代码

python -m pip install -U "huggingface_hub[cli]"

hf download nvidia/LocateAnything-3B \
  --local-dir LocateAnything-3B

将整个 LocateAnything-3B/ 目录压缩并上传至服务器 /opt/proj/：

bash 复制代码

tar -czf LocateAnything-3B.tar.gz LocateAnything-3B

服务器端解压：

bash 复制代码

cd /opt/proj
tar -xzf LocateAnything-3B.tar.gz

检查模型目录：

bash 复制代码

ls -lh /opt/proj/LocateAnything-3B

关键文件至少应包括：

text 复制代码

config.json
tokenizer_config.json
model.safetensors.index.json
model-00001-of-00002.safetensors
model-00002-of-00002.safetensors
modeling_locateanything.py
processing_locateanything.py

模型目录通常约 7GB 以上；可检查：

bash 复制代码

du -sh /opt/proj/LocateAnything-3B

8. 本地离线加载测试

重要：传给 LocateAnythingWorker() 的本地模型路径必须真实存在。若路径不存在，Transformers 可能把路径误当成 Hugging Face 仓库 ID，并报 Repo id must be in the form ...。

bash 复制代码

conda activate locateanything
cd /opt/proj/Eagle-main/Embodied

python - <<'PY'
import os
import torch
from locateanything_worker import LocateAnythingWorker

model_path = "/opt/proj/LocateAnything-3B"

print("model exists:", os.path.isdir(model_path))
print("tokenizer_config exists:",
      os.path.exists(os.path.join(model_path, "tokenizer_config.json")))
print("torch:", torch.__version__)
print("cuda available:", torch.cuda.is_available())
print("gpu:", torch.cuda.get_device_name(0) if torch.cuda.is_available() else "N/A")

worker = LocateAnythingWorker(model_path)
print("MODEL_LOAD_OK")
PY

若最后出现：

text 复制代码

MODEL_LOAD_OK

则代码、模型、CUDA 推理链路已通。

常见但可暂时忽略的提示：

text 复制代码

flash_attn is not available ... falling back to sdpa
magi_attention not available, falling back to sdpa
torch_dtype is deprecated

这些提示表示当前环境使用 SDPA 回退路径，不等于模型加载失败。

9. 常见故障排查

A. Conda 仍访问官方源 / `Network is unreachable`

使用创建环境时的 --override-channels，不要依赖已有 defaults 配置：

bash 复制代码

conda create -n locateanything python=3.10 -y --override-channels \
  -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main \
  -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r

B. GitHub / Hugging Face 访问超时

在联网机器下载代码 ZIP 和完整模型目录，再上传到服务器。

C. `Repo id must be in the form ...`

通常是本地模型路径不存在或写错。确认：

bash 复制代码

ls -ld /opt/proj/LocateAnything-3B
ls -l /opt/proj/LocateAnything-3B/tokenizer_config.json

D. CUDA OOM

先执行 nvidia-smi 检查其他进程。
使用脚本默认的 --max-size 1024。
必要时把 --max-size 再降到 768。

LocateAnything Linux 部署操作记录

1. 目录规划

2. 前置检查：GPU、驱动与系统

3. 创建 Conda 环境

4. 安装系统工具

5. 获取 Eagle / LocateAnything 源代码

方案 A：服务器能访问 GitHub

方案 B：服务器不能访问 GitHub（本次采用）

6. 安装 LocateAnything Python 依赖

7. 获取 LocateAnything-3B 模型权重

方案 A：服务器能访问 Hugging Face

方案 B：服务器不能访问 Hugging Face（本次采用）

8. 本地离线加载测试

9. 常见故障排查

A. Conda 仍访问官方源 / Network is unreachable

B. GitHub / Hugging Face 访问超时

C. Repo id must be in the form ...

D. CUDA OOM

A. Conda 仍访问官方源 / `Network is unreachable`

C. `Repo id must be in the form ...`