YOLOE代码仓库路径说明，新手不迷路
你是否刚接触YOLOE镜像，面对终端界面却不知道从哪里开始？
是否在找模型文件时翻遍目录却无从下手？
又或者看到predict_text_prompt.py这样的脚本名，却不确定该在哪个路径下运行？
别担心，这篇文章就是为你准备的。我们不讲复杂的原理，也不堆砌技术术语，只用最直白的方式告诉你：代码放在哪、环境怎么进、脚本怎么跑。让你在拿到YOLOE镜像后，三分钟内就能上手运行第一个检测任务。
1. 镜像核心信息一览
当你成功启动YOLOE官方镜像后，系统已经为你预装好了所有依赖和项目代码。但要顺利使用，首先要搞清楚几个关键信息：
| 项目 | 值 |
|---|---|
| 代码仓库路径 | /root/yoloe |
| Conda环境名称 | yoloe |
| Python版本 | 3.10 |
| 主要依赖库 | torch,clip,mobileclip,gradio |
这些信息决定了你后续的所有操作起点。记住一句话：所有操作都从/root/yoloe开始。
2. 第一步：激活环境并进入项目目录
容器启动后，默认处于基础Linux环境，并未自动激活YOLOE所需的Python环境。你需要手动执行以下两步：
2.1 激活Conda环境
conda activate yoloe这一步会切换到名为yoloe的独立Python环境，其中已安装了PyTorch、CLIP等必要库。如果你跳过这步直接运行Python脚本，大概率会遇到“ModuleNotFoundError”。
提示：可以通过
conda env list查看当前可用环境，确认yoloe是否存在。
2.2 进入项目主目录
cd /root/yoloe这是整个项目的根目录，所有预测、训练、配置文件都在这里。你可以通过ls命令查看内容：
ls你应该能看到类似以下的文件结构：
predict_text_prompt.py predict_visual_prompt.py predict_prompt_free.py train_pe.py train_pe_all.py pretrain/ ultralytics/没错，你现在已经在“战场”中央了。
3. 如何运行三种不同模式的推理？
YOLOE支持三种提示方式：文本提示、视觉提示、无提示。每种都有对应的脚本，且都在根目录下，无需额外配置路径。
3.1 文本提示检测（Text Prompt）
适用于你想让模型识别特定类别的场景，比如只检测“person, dog, cat”。
运行命令如下：
python predict_text_prompt.py \ --source ultralytics/assets/bus.jpg \ --checkpoint pretrain/yoloe-v8l-seg.pt \ --names person dog cat \ --device cuda:0--source：输入图片路径，示例中是项目自带的一张公交车照片。--checkpoint：模型权重文件位置，位于pretrain/目录下。--names：你要检测的类别名称列表。--device：指定使用GPU进行推理。
运行后，程序会在同级目录生成带标注框和分割掩码的输出图像。
小技巧：你可以把
--source换成自己上传的图片路径，例如/root/yoloe/my_image.jpg，即可测试自定义图片。
3.2 视觉提示检测（Visual Prompt）
这种模式允许你用一张“参考图+区域框”作为提示，让模型在目标图中找出相似物体。
运行命令更简单：
python predict_visual_prompt.py该脚本默认会启动一个Gradio交互界面，打开浏览器即可通过拖拽图片、画框来完成视觉提示操作。
注意：如果你是在远程服务器上运行，请确保端口已映射，并使用
-p 7860:7860启动容器，否则无法访问Web界面。
3.3 无提示检测（Prompt-Free）
顾名思义，不需要任何提示词或参考图，模型自动识别画面中所有可见物体。
运行命令：
python predict_prompt_free.py同样会调用Gradio界面，上传图片后自动完成开放词汇表检测与实例分割。
这个模式最接近“人眼感知一切”的理念，适合探索性分析或零样本迁移任务。
4. 模型加载也可以用代码写！
除了命令行脚本，YOLOE还支持Python API方式调用，特别适合集成到自己的项目中。
4.1 使用from_pretrained快速加载模型
from ultralytics import YOLOE # 自动下载并加载指定模型 model = YOLOE.from_pretrained("jameslahm/yoloe-v8l-seg")这行代码会自动从Hugging Face下载yoloe-v8l-seg模型，省去手动管理权重文件的麻烦。
4.2 手动指定本地权重路径
如果你不想依赖网络下载，可以直接指向本地.pt文件：
model = YOLOE("pretrain/yoloe-v8l-seg.pt")然后调用model.predict()方法进行推理：
results = model.predict(source="ultralytics/assets/bus.jpg", names=["person", "dog"]) results.show()这种方式灵活度更高，便于批量处理或多任务调度。
5. 训练与微调：你的模型你做主
YOLOE不仅擅长推理，还能快速适配新场景。镜像中提供了两个训练脚本，分别对应轻量微调和全参数训练。
5.1 线性探测（Linear Probing）
仅训练提示嵌入层（prompt embedding），速度快，适合资源有限的情况。
python train_pe.py该模式冻结主干网络，只更新最后的文本投影头，可在几分钟内完成一轮训练。
5.2 全量微调（Full Tuning）
训练所有参数，获得最佳性能表现。
python train_pe_all.py建议：
- 对于
v8s模型，训练 160 个epoch； - 对于
v8m/l模型，训练 80 个epoch 即可收敛。
提醒：训练前请确认GPU显存充足，尤其是大模型+大批量时容易OOM。
6. 常见问题与避坑指南
即使有了预置镜像，新手仍可能踩一些“看似 trivial 实则卡人”的坑。以下是高频问题及解决方案。
6.1 报错 “No module named 'ultralytics'”
原因：未激活yoloe环境。
✅ 正确做法：
conda activate yoloe cd /root/yoloe python predict_text_prompt.py不要在(base)环境下直接运行脚本！
6.2 提示 “File not found: pretrain/yoloe-v8l-seg.pt”
原因：权重文件缺失。
解决方法有两种：
手动下载
前往 Hugging Face 页面 https://huggingface.co/jameslahm/yoloe-v8l-seg 下载.pt文件，上传至/root/yoloe/pretrain/目录。改用
from_pretrained
直接使用API自动下载：model = YOLOE.from_pretrained("jameslahm/yoloe-v8l-seg")
6.3 Gradio界面打不开？
常见于远程服务器部署场景。
检查点：
- 容器是否启用了端口映射？应包含
-p 7860:7860 - 防火墙是否放行7860端口？
- 启动脚本是否绑定到了
0.0.0.0？部分脚本需修改launch(host="0.0.0.0")
修复示例：
gr.Interface(...).launch(server_name="0.0.0.0", server_port=7860)6.4 显存不足（CUDA Out of Memory）
建议调整以下参数：
- 减小
batch_size - 使用较小模型如
yoloe-v8s-seg - 关闭不必要的进程
也可在运行时指定低显存模式（若支持）：
export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:1287. 总结：新手上路 checklist
现在你已经掌握了YOLOE镜像的核心使用路径。最后送你一份“开机即用”清单，照着做就不会迷路。
7.1 必做四件事
- ✅ 启动容器后第一件事：
conda activate yoloe - ✅ 第二件事：
cd /root/yoloe - ✅ 查看自带示例图：
ls ultralytics/assets/ - ✅ 尝试运行第一个脚本：
python predict_text_prompt.py
7.2 推荐学习路径
- 先跑通文本提示 → 理解输入输出格式
- 再试视觉提示 → 感受交互式检测魅力
- 接着玩无提示模式 → 体验“看见一切”的能力
- 最后尝试微调 → 让模型学会识别新物体
只要你能顺利运行这三个predict_*.py脚本，就已经跨过了最难的入门门槛。
YOLOE的设计哲学是“高效、统一、开放”，而这个镜像的目标则是“开箱即用、拒绝折腾”。希望这篇指南帮你少走弯路，把时间花在真正重要的事情上——比如设计更好的提示词、发现更有趣的检测结果，或是构建属于你自己的智能应用。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
