Помощь
Добро пожаловать на страницу справки Ultralytics. Здесь собраны практические руководства, политики и часто задаваемые вопросы, которые помогут тебе работать с моделями и репозиториями Ultralytics YOLO.
- Часто задаваемые вопросы (FAQ): здесь ты найдёшь ответы на распространённые вопросы и решения проблем, с которыми сталкиваются пользователи и участники сообщества Ultralytics YOLO.
- Руководство для участников: узнай о правилах внесения изменений, в том числе о том, как отправлять запросы на слияние, сообщать об ошибках и многое другое.
- Руководство по непрерывной интеграции (CI): узнай о процессах CI, которые мы используем, и отчётах о статусе каждого репозитория Ultralytics.
- Лицензионное соглашение с участником (CLA): ознакомься с CLA, чтобы понять права и обязанности, связанные с участием в проектах Ultralytics.
- Руководство по минимальному воспроизводимому примеру (MRE): узнай, как создать MRE, необходимый для быстрого и эффективного решения проблем, о которых сообщают пользователи.
- Правила поведения: наши правила для сообщества помогают поддерживать уважительную и открытую атмосферу для всех участников.
- Политика в области охраны окружающей среды, здоровья и безопасности (EHS): узнай о наших обязательствах по обеспечению устойчивого развития и благополучия всех заинтересованных сторон.
- Политика безопасности: ознакомься с нашими протоколами безопасности и порядком сообщения об уязвимостях.
- Политика конфиденциальности: прочитай нашу политику конфиденциальности, чтобы узнать, как мы защищаем твои данные и соблюдаем конфиденциальность во всех наших сервисах и процессах.
Рекомендуем ознакомиться с этими материалами — так тебе будет проще и продуктивнее работать. Если нужна дополнительная помощь, обратись к нам через раздел Issues на GitHub или сообщество Ultralytics.
Часто задаваемые вопросы#
Ultralytics YOLO (ты смотришь только один раз) — это современная модель обнаружения объектов в реальном времени. Последняя версия, YOLO26, обеспечивает более быстрый и лёгкий инференс, а её сквозная голова без NMS доступна как опция; модель оптимизирована для периферийных устройств и устройств с низким энергопотреблением, поэтому подходит для самых разных задач — от видеоаналитики в реальном времени до передовых исследований в области машинного обучения. Благодаря эффективности обнаружения объектов на изображениях и видео YOLO стала популярным выбором среди компаний и исследователей, которые хотят интегрировать в свои проекты надёжные возможности компьютерного зрения.
Подробнее о текущем выпуске читай в документации YOLO26. О предстоящем семействе моделей можно узнать на странице YOLO27 (скоро): модели пока недоступны, дата запуска не назначена.
Внести вклад в репозитории Ultralytics YOLO просто. Сначала прочитай руководство для участников, чтобы узнать правила отправки запросов на слияние, сообщений об ошибках и других материалов. Также нужно подписать лицензионное соглашение с участником (CLA), чтобы твой вклад был юридически признан. О том, как эффективно сообщать об ошибках, читай в руководстве по минимальному воспроизводимому примеру (MRE).
Ultralytics Platform — это решение без кода для управления проектами машинного обучения. Оно позволяет размечать данные, обучать и развёртывать модели, например YOLO26, в одном месте, используя облачное обучение, метрики обучения в реальном времени и управление наборами данных. Платформа охватывает весь процесс — от подготовки данных до развёртывания модели — и подходит как новичкам, так и опытным пользователям.
Чтобы начать работу, посети страницу быстрого старта на платформе Ultralytics.
Непрерывная интеграция (CI) в Ultralytics включает автоматизированные процессы, которые обеспечивают целостность и качество кодовой базы. Наша конфигурация CI включает развертывание Docker, проверку неработающих ссылок, анализ CodeQL и публикацию пакетов в PyPI. Эти процессы помогают поддерживать стабильность и безопасность репозиториев: при каждом добавлении кода автоматически запускаются тесты и проверки.
Подробнее читай в руководстве по непрерывной интеграции (CI).
Ultralytics серьёзно относится к конфиденциальности данных. В нашей Политике конфиденциальности описано, как мы собираем и используем анонимизированные данные для улучшения пакета YOLO, уделяя первостепенное внимание конфиденциальности и контролю со стороны пользователей. Мы соблюдаем строгие правила защиты данных, чтобы обеспечить безопасность твоей информации.
Комментарии614
Задай вопрос, поделись результатами или помоги кому-нибудь.
si-open
please add a ruby gem for YOLO thanks
1yuchoyao
Hi Ultralytics team,
I have been trying to use YOLOv10 on the Windows platform these days, but unfortunately it has not been realized, because of a small problem I once encountered. I have searched for all similar problems, but their solution cannot solve my problem, I hope you can help me, thank you very much! I wrote a piece of Python code to use YOLOv10 for training, here is the code content, I am using the coco dataset
from ultralytics import YOLOv10 import supervision as sv import cv2 import os
classes = { 0: 'person', 1: 'bicycle', 2: 'car', 3: 'motorcycle', 4: 'airplane', 5: 'bus', 6: 'train', 7: 'truck', 8: 'boat', 9: 'traffic light', 10: 'fire hydrant', 11: 'stop sign', 12: 'parking meter', 13: 'bench', 14: 'bird', 15: 'cat', 16: 'dog', 17: 'horse', 18: 'sheep', 19: 'cow', 20: 'elephant', 21: 'bear', 22: 'zebra', 23: 'giraffe', 24: 'backpack', 25: 'umbrella', 26: 'handbag', 27: 'tie', 28: 'suitcase', 29: 'frisbee', 30: 'skis', 31: 'snowboard', 32: 'sports ball', 33: 'kite', 34: 'baseball bat', 35: 'baseball glove', 36: 'skateboard', 37: 'surfboard', 38: 'tennis racket', 39: 'bottle', 40: 'wine glass', 41: 'cup', 42: 'fork', 43: 'knife', 44: 'spoon', 45: 'bowl', 46: 'banana', 47: 'apple', 48: 'sandwich', 49: 'orange', 50: 'broccoli', 51: 'carrot', 52: 'hot dog', 53: 'pizza', 54: 'donut', 55: 'cake', 56: 'chair', 57: 'couch', 58: 'potted plant', 59: 'bed', 60: 'dining table', 61: 'toilet', 62: 'tv', 63: 'laptop', 64: 'mouse', 65: 'remote', 66: 'keyboard', 67: 'cell phone', 68: 'microwave', 69: 'oven', 70: 'toaster', 71: 'sink', 72: 'refrigerator', 73: 'book', 74: 'clock', 75: 'vase', 76: 'scissors', 77: 'teddy bear', 78: 'hair drier', 79: 'toothbrush' }
model = YOLOv10(r'D:\python3_12\yolov10-main\weights\yolov10b.pt')
image = cv2.imread("E:\coco_test_renamed")
results = model(source=image, conf=0.25, verbose=False)[0] detections = sv.Detections.from_ultralytics(results) box_annotator = sv.BoxAnnotator()
labels = [ f"{classes[class_id]} {confidence:.2f}" for class_id, confidence in zip(detections.class_id, detections.confidence) ] annotated_image = box_annotator.annotate( image.copy(), detections=detections, labels=labels )
cv2.imshow('result', annotated_image) cv2.waitKey() cv2.destroyAllWindows() cv2.imwrite('annotated_dog.jpeg', annotated_image)
After I run the code, the program will report an ERROR, thus terminating the run
D:\python3_12\Anaconda\anaconda3\envs\yolov10_torch\python.exe D:\python3_12\yolov10-main\test.py Traceback (most recent call last): File "D:\python3_12\yolov10-main\test.py", line 28, in image = cv2.imread("E:\coco_test_renamed") ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "D:\python3_12\yolov10-main\ultralytics\utils\patches.py", line 26, in imread return cv2.imdecode(np.fromfile(filename, np.uint8), flags) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PermissionError: [Errno 13] Permission denied: 'E:\coco_test_renamed'
Process finished with exit code 1
I have tried all methods to solve this problem without success, including changing file permissions on windows and using python to change file permissions and running pycharm with administrator permissions, but all have failed, especially since this problem only occurs when running YOLO.
If you can help me, I will appreciate it very much. Thank you very much.
1
Glenn JocherUltralyticsHi there,
Thank you for reaching out and providing detailed information about your issue. It looks like you're encountering a
PermissionErrorwhen trying to read the image file with OpenCV on your Windows platform.To help resolve this, please consider the following steps:
-
Verify File Path and Permissions: Ensure that the file path
"E:\\coco_test_renamed"is correct and that the file exists. Also, check the file permissions to make sure your script has read access to this file. -
Check File Path Format: Windows paths can sometimes be tricky. Try using raw strings or double backslashes to avoid escape character issues:
image = cv2.imread(r"E:\coco_test_renamed") -
Update Packages: Make sure you are using the latest versions of all relevant packages, including
ultralytics,supervision, andopencv-python. You can update them using pip:pip install --upgrade ultralytics supervision opencv-python -
Minimum Reproducible Example: If the issue persists, providing a minimum reproducible example can greatly help in diagnosing the problem. You can find guidance on creating one here: Minimum Reproducible Example Guide.
Here is a simplified version of your code to help isolate the issue:
import cv2 # Ensure the file path is correct and accessible image_path = r"E:\coco_test_renamed" image = cv2.imread(image_path) if image is None: print(f"Failed to load image from {image_path}") else: print("Image loaded successfully")Run this snippet to check if the image loads correctly. If it doesn't, the issue is likely with the file path or permissions.
Please try these steps and let us know if the problem persists. We're here to help!
3-
yuchoyao
Hi Thank you very much for your help.
After testing and adjusting the source code, I found that the real problem is not file permissions, but def imread(filename: str, flags: int = cv2.IMREAD_COLOR) This function can only accept a single image as the input parameter, and I wrote the file path as the folder path instead of the image path when I entered the parameter, so I caused a Permissionerror: [errno 13] permission denied ERROR. It is true that we should not only see the surface of ERROR but also understand the underlying causes of ERROR.
Thanks again for your help!
4
Glenn JocherUltralytics@YaoEndless hi there,
Thank you for the update and for identifying the root cause of the issue! It's great to hear that you were able to pinpoint the problem with the file path.
Indeed, the
cv2.imreadfunction expects a path to a single image file, not a directory. It's a common mistake, and your experience will certainly help others who might encounter a similar issue.If you have any further questions or run into other issues, feel free to reach out. We're here to help! For more detailed guidance on various topics, you can always refer to our Ultralytics Help page.
Happy coding! 😊
Juanrp7
Hola comunidad de Ultralytics, Estoy desarrollando un proyecto de detección y conteo de personas mediante cámaras CCTV utilizando el protocolo RTSP, orientado a generar analítica para varios centros comerciales con un total aproximado de 400 cámaras. Mi configuración actual es la siguiente:
Modelo: YOLOv11m GPU: NVIDIA RTX 4050 RAM: 64 GB CPU: Intel Core i5 de 12ª generación
Problema identificado: Al intentar procesar únicamente 3 streams RTSP de forma simultánea, el consumo de CPU se dispara de manera considerable, lo cual me preocupa de cara a escalar la solución. Tengo dos preguntas:
- ¿Por qué se dispara el consumo de CPU al procesar múltiples streams RTSP? ¿Es un problema relacionado con la decodificación de video, con la gestión de los streams, o con algún cuello de botella en la integración con YOLO? ¿Existe alguna configuración o práctica recomendada para mitigarlo?
- ¿Qué infraestructura recomiendan para escalar este proyecto a 400 cámaras? ¿Es más viable una solución on-premise con hardware dedicado, o convendría migrar a una infraestructura en la nube (AWS, GCP, Azure)? Agradezco cualquier referencia de arquitecturas similares que hayan implementado con Ultralytics YOLO a gran escala. Gracias de antemano por su ayuda.
Glenn JocherUltralyticsEl pico de CPU suele venir principalmente de la ingesta/decodificación RTSP (FFmpeg/OpenCV), buffering y preprocesado por stream, no del forward en GPU; al abrir varios RTSP a la vez se multiplican esos hilos de decodificación y la CPU se convierte en el cuello de botella aunque la inferencia vaya en la RTX. Para mitigarlo, normalmente ayuda bajar FPS efectivo y resolución (p. ej.
vid_stride+imgsz), usar modo multi-stream para procesar varios RTSP en un solo proceso, y asegurarte de iterar en streaming (generador) como en la guía de fuentes de inferencia (Stream y Multi-Stream); si además haces conteo con IDs, revisa Track mode porque el tracking añade carga extra.Para 400 cámaras, casi siempre termina siendo una arquitectura distribuida (varios nodos) y dimensionada por “cámaras × FPS objetivo × resolución”: on‑prem cerca de las cámaras suele ser más viable por ancho de banda y latencia, y un enfoque híbrido (edge para inferir + cloud para eventos/métricas) suele escalar mejor; como referencia de decisiones/criterios, mira buenas prácticas de despliegue y el artículo sobre edge vs cloud para desplegar YOLO26. Si compartes resolución/codec (H.264/H.265), FPS de cámara, FPS objetivo por stream y el comando/código exacto que usas, puedo ayudarte a estimar capacidad por GPU y dónde se está yendo la CPU.
Juanrp7
Hola Glenn, Muchas gracias por tu respuesta. Quisiera compartir una actualización y ampliar un poco el contexto. Después de realizar algunos ajustes en el código, logré reducir el consumo de CPU aproximadamente en un 70%, lo cual fue una mejora importante. Sin embargo, como mencioné en la publicación inicial, actualmente estoy realizando pruebas únicamente con 3 cámaras RTSP. Aunque el consumo de CPU disminuyó considerablemente, la precisión del conteo también bajó, situándose ahora entre 30% y 40%. Mi objetivo es alcanzar al menos una precisión del 80%–90%. En este punto, me gustaría entender mejor:- ¿Cuántas cámaras puede soportar mi arquitectura actual manteniendo un buen rendimiento y una precisión aceptable?
- ¿Cuál sería la arquitectura ideal para desplegar entre 5 y 10 cámaras con una precisión cercana al 90%?
Infraestructura actual- GPU: NVIDIA RTX 4050 (6GB VRAM)
- RAM: 64 GB
- CPU: Intel Core i5 (12ª generación)
- Sistema operativo: Ubuntu Server
📊 Configuración actual de cámaras (Etapa 1 – 3 cámaras)Cámara Resolución Codec FPS Cámara vid_stride FPS procesado aprox. Costa 740×480 H.265 30 3 ~10 FPS Tomaticos 740×480 H.264 30 3 ~6.7 FPS Supermercado 740×480 H.265 30 3 ~10 FPS
🖥 Arquitectura actual de despliegue Servidor Linux (147.xxx.x.xxx) ┌──────────────────────────────────────────── │ SERVIDOR LINUX (147.XXX.X.XXX) │ │ launcher.py (supervisor) │ ├── conteo_entrada_costa_v2.py → :8081/stream │ ├── conteo_tomaticos_lineas.py → :8082/stream │ └── supermercado.py → :8083/stream │ │ Cada proceso ejecuta: │ RTSP 704×480 → YOLO11n (GPU) → ByteTrack → MJPEG HTTP └──────────────────────────────────────────── Cliente (PC Windows) HTTP (puertos 8081–8083) ▼ ┌──────────────────────────────────────────── │ PC Windows │ → dashboard.html (visualiza las 3 cámaras) └──────────────────────────────────────────── Actualmente, cada cámara se ejecuta en un proceso Python independiente, y cada uno realiza:- Ingesta RTSP
- Inferencia con YOLO11n en GPU
- Tracking con ByteTrack
- Publicación vía MJPEG sobre HTTP
📍 Próxima etapa – Escalamiento En una segunda fase, el objetivo es desplegar la solución en uno de los 8 centros comerciales, el cual cuenta con aproximadamente 100–150 cámaras. Antes de avanzar hacia esa etapa, me gustaría conocer su recomendación sobre:- Número estimado de cámaras que puede soportar una GPU bajo esta configuración.
- Si utilizar modo multi-stream en un solo proceso mejoraría significativamente la eficiencia frente al modelo actual de procesos independientes.
- Buenas prácticas para mantener una precisión cercana al 90% al escalar.
- Arquitectura recomendada para 5–10 cámaras con alta precisión.
- Arquitectura distribuida sugerida para un escenario de 100–150 cámaras.
Código Fuente
El código fuente y la implementación actual pueden consultarse en:
Glenn JocherUltralyticsLa bajada de precisión casi siempre viene de que al recortar carga (p. ej., subir
vid_stridey/o bajar FPS efectivo) el tracking se vuelve inestable: ByteTrack pierde asociaciones/IDs y los cruces de línea dejan de contarse bien, así que para llegar a 80–90% normalmente necesitas mantener más “densidad temporal” (más frames útiles) y recortar CPU por otro lado, idealmente usando el substream de la cámara (misma escena pero menor bitrate/resolución) y/o decodificación acelerada en lugar de saltarte tantos frames; también ayuda ajustar el YAML del tracker a tu escena (umbral de matching/buffer, etc.) partiendo de los configs en el directorio de trackers.Sobre capacidad, con una RTX 4050 de 6GB el límite suele ser la ingesta/decodificación + tracking (y el MJPEG también consume CPU), no tanto la inferencia; si consigues decodificar “barato” y usas un modelo ligero (te recomendaría probar Ultralytics YOLO con
yolo26n.pt/yolo26s.pt), 5–10 cámaras a 480p con FPS moderado suele ser alcanzable, pero la forma fiable de estimarlo es medir 1 cámara y escalar hasta saturar CPU/GPU (porque depende mucho de cuánta gente haya en escena y del codec H.265 vs H.264).Si compartes en texto (sin HTML) el comando exacto y la parte mínima del pipeline de tu repo repositorio
analiticamque reproduce el conteo, junto con la salida deyolo checks, podemos afinar el dimensionamiento y ver si tienes cuellos por múltiples instalaciones/rutas (guía útil: Troubleshooting Common YOLO Issues).
Bill StrumGot it working, I have a path issue in PCharm that I have to track down
Thanks
On Sat, Feb 21, 2026 at 4:23 PM Glenn Jocher @.***> wrote:
This usually means a version/path mismatch: the yolo26m-seg.pt checkpoint was saved with a build that includes Segment26, but the ultralytics you’re importing in that conda env doesn’t (or you have multiple installs shadowing each other), so please upgrade, restart Python, then paste the text output from yolo checks and the full traceback if it still fails (see the Troubleshooting Common YOLO Issues https://docs.ultralytics.com/guides/yolo-common-issues/ guide for common env conflicts).
pip install -U ultralytics yolo checks
import ultralyticsprint(ultralytics.version)print(ultralytics.file)
— Reply to this email directly, view it on GitHub https://github.com/orgs/ultralytics/discussions/8027#discussioncomment-15884673, or unsubscribe https://github.com/notifications/unsubscribe-auth/AI2XRUL3AMQKVRTST64HVST4NDEELAVCNFSM6AAAAABCZTU2BOVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKOBYGQ3DOMY . You are receiving this because you commented.Message ID: @.*** com>
Glenn JocherUltralyticsGlad you got it working — in PyCharm this is almost always the Run/Debug “Python interpreter” pointing to a different env than your terminal, so please double-check
sys.executableand thatultralytics.__file__resolves inside the same conda env/site-packages (and if it doesn’t, runultralytics.utils.checks.check_multiple_install()to catch shadowed installs); the env-conflict patterns are also covered in the Troubleshooting Common YOLO Issues guide.import sys, ultralytics print(sys.executable) print(ultralytics.__version__) print(ultralytics.__file__)
Bill StrumI am getting this error when trying to run YOLO using model yolo26m-seg
AttributeError: Can't get attribute 'Segment26' on <module 'ultralytics.nn.modules.head' from 'C:\Users\User\.conda\envs\AI_Test\Lib\site-packages\ultralytics\nn\modules\head.py'>
I'm using version: Ultralytics version: 8.3.169
Here is the code 👍 import ultralytics from ultralytics import YOLO
print(f"Ultralytics version: {ultralytics.version}")
model = YOLO("yolo26m-seg.pt")
Use one-to-one head (default, no NMS required)
#results = model.predict("images/dog.jpg", conf=0.15) results = model.predict("images/mixed_traffic_1.jpg", conf=0.1)
Display the result
for result in results: result.show()
Please advise on problem fix.
CB BIll
Glenn JocherUltralyticsThis usually means a version/path mismatch: the
yolo26m-seg.ptcheckpoint was saved with a build that includesSegment26, but theultralyticsyou’re importing in that conda env doesn’t (or you have multiple installs shadowing each other), so please upgrade, restart Python, then paste the text output fromyolo checksand the full traceback if it still fails (see the Troubleshooting Common YOLO Issues guide for common env conflicts).pip install -U ultralytics yolo checksimport ultralytics print(ultralytics.__version__) print(ultralytics.__file__)
nono2512
YOLO26n OpenVINO export segfaults on Intel N100 GPU
- Hardware: Intel N100 (Alder Lake-N, UHD Graphics)
- OS: Ubuntu 24.04, LXC
- OpenVINO: 2025.4.1
- Ultralytics: 8.4.14
- Drivers: intel-compute-runtime 26.05
GPU works with Intel models (person-detection-0202) but segfaults on YOLO26n_openvino_model with device="intel:gpu"
995742853
Hi. I noticed in ultralytics/utils/torch_utils.py, the initialize_weights function sets eps=0.001 and momentum=0.03 for BatchNorm2d layers, instead of the PyTorch defaults.
Could you briefly explain the reasoning behind these values? Do they significantly improve model performance or robustness?
Thanks!
Glenn JocherUltralyticsThose BatchNorm2d settings (
eps=1e-3,momentum=0.03) are a long-standing YOLO training convention rather than a random tweak: the slightly largerepsis mainly for numerical stability (especially with mixed precision and aggressive augmentations), and the lowermomentummakes the running mean/var update more smoothly (less noisy), which can help robustness when batch composition varies. In practice they rarely “unlock” big mAP gains by themselves, but they tend to reduce edge-case instability and keep training behavior consistent across YOLO models; see the background in our Batch Normalization overview.995742853
Thank you for your reply. Wish you a wonderful day!
keykin
Hi, how to install ultralytics without deps matplotlib, because armbian can not run pip with --no-deps but can only run pipx without --no-deps. Is there any packages or CLI commands can be used? Thanks a lot.
keykin
I have found a way by modifying the pyproject.toml and executing pipx install.
Glenn JocherUltralytics@elsaoreen if you’ve already exported to NCNN, you can load the exported
*_ncnn_modelfolder withYOLO(...)and pass Picamera2 frames (asnp.ndarray) directly; see the NCNN integration guide for the expected export/load workflow.from picamera2 import Picamera2 import cv2 from ultralytics import YOLO model = YOLO("yolo26n_ncnn_model") # path to exported NCNN model folder picam2 = Picamera2() picam2.configure(picam2.create_preview_configuration(main={"format": "RGB888"})) picam2.start() while True: frame = picam2.capture_array() # RGB frame = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR) # Ultralytics/OpenCV-friendly _ = model.predict(source=frame, imgsz=640, conf=0.25, verbose=False)@keykin
matplotlibis currently a required dependency inultralytics, so “no-matplotlib” installs aren’t officially supported, but if you want to avoid editingpyproject.toml,pipxcan pass through--no-depsvia--pip-argsand then you can selectively add packages withpipx inject(see pipx install docs and the pipx inject examples).pipx install ultralytics --pip-args="--no-deps" pipx inject ultralytics numpy opencv-python pillow pyyaml requests scipy
elsaoreen
I am having trouble integrating the code to run YOLO NCNN model with picamera2 module.
LJY886321
onnx输出的[1,6,8400],中的6是包含一个类别数吗,为什么我的pt文件是两个类别,而onnx总是一个类别数呢
Glenn JocherUltralytics[1, 6, 8400]里这个6通常不是“只有 1 个类别”,而是4 + nc:前 4 个通道是框坐标,后nc个通道是每个类别的分数;所以当6=4+2时,恰好表示你的模型是 2 类(与你的pt一致),只是导出后的张量结构里没有单独的 objectness 通道(端到端/NMS-free 头一般用 per-class score 形式)。相关输出说明见导出模型的输出张量说明。如果你愿意,把你的导出命令(是否带了nms=True)和 ONNX 的输出节点名贴在这里,我可以帮你对齐后处理的维度/转置方式。