开始使用

Ultralytics YOLO 常见问题解答 (FAQ)

本常见问题解答部分介绍用户在使用 Ultralytics YOLO 代码仓库时可能遇到的常见问题和疑难情况。

常见问题#

  • Ultralytics 是一家专注于先进目标检测和图像分割模型的计算机视觉 AI 公司,重点开发 YOLO(You Only Look Once)系列。我们的产品和服务包括:

  • 不可以。YOLO27正在进行最终的研发工作,预计于今年晚些时候发布,但发布日期尚未确定。文档预览了其功能、初步基准测试结果,以及发布后使用模型的示例。目前的项目请继续使用 YOLO26。

  • 使用 pip 安装 Ultralytics 软件包很简单:

    pip install ultralytics

    如需安装最新开发版本,请直接从 GitHub 代码仓库安装:

    pip install git+https://github.com/ultralytics/ultralytics.git

    详细的安装说明请参阅快速入门指南。

  • 最低要求:

    • Python 3.8+
    • PyTorch 1.8+
    • 兼容 CUDA 的 GPU(用于 GPU 加速)

    推荐配置:

    • NVIDIA GPU
    • 8GB+ RAM
    • 50GB+ 可用磁盘空间(用于存储数据集和训练模型)

    如需排查常见问题,请访问 YOLO 常见问题页面。

  • 训练自定义 YOLO 模型的步骤:

    1. 按照 YOLO 格式准备数据集(图像及对应的标签 txt 文件)。

    2. 创建 YAML 文件,描述数据集结构和类别(参见数据集 YAML 示例)。

    3. 使用以下 Python 代码开始训练:

      from ultralytics import YOLO
      
      # 加载模型
      model = YOLO("yolo26n.yaml")  # 从头开始构建新模型
      model = YOLO("yolo26n.pt")  # 加载预训练模型(推荐用于训练)
      
      # 训练模型
      results = model.train(data="path/to/your/data.yaml", epochs=100, imgsz=640)

    如需更深入的指南,包括数据准备和高级训练选项,请参阅训练指南。

  • Ultralytics 提供多种适用于不同任务的预训练 YOLO26 模型:

    • 目标检测:YOLO26n、YOLO26s、YOLO26m、YOLO26l、YOLO26x
    • 实例分割:YOLO26n-seg、YOLO26s-seg、YOLO26m-seg、YOLO26l-seg、YOLO26x-seg
    • 语义分割:YOLO26n-sem、YOLO26s-sem、YOLO26m-sem、YOLO26l-sem、YOLO26x-sem
    • 深度估计:YOLO26n-depth、YOLO26s-depth、YOLO26m-depth、YOLO26l-depth、YOLO26x-depth
    • 分类:YOLO26n-cls、YOLO26s-cls、YOLO26m-cls、YOLO26l-cls、YOLO26x-cls
    • 姿态估计:YOLO26n-pose、YOLO26s-pose、YOLO26m-pose、YOLO26l-pose、YOLO26x-pose
    • 有向目标检测 (OBB):YOLO26n-obb、YOLO26s-obb、YOLO26m-obb、YOLO26l-obb、YOLO26x-obb

    这些模型的大小和复杂度各不相同,在速度和准确率之间提供不同的权衡。探索完整的预训练模型系列,为你的项目找到最合适的模型。

  • 使用训练好的模型进行推理的步骤:

    from ultralytics import YOLO
    
    # 加载模型
    model = YOLO("path/to/your/model.pt")
    
    # 执行推理
    results = model("path/to/image.jpg")
    
    # 处理结果
    for r in results:
        print(r.boxes)  # 打印 bbox 预测结果
        print(r.masks)  # 打印掩码预测结果
        print(r.probs)  # 打印类别概率

    如需了解高级推理选项,包括批处理和视频推理,请参阅详细的预测指南。

  • 是的。Ultralytics 模型支持部署到各种平台:

    • 边缘设备:使用 TensorRT、ONNX 或 OpenVINO,在 NVIDIA Jetson 或 Raspberry Pi 等设备上优化推理。
    • 移动设备:将模型转换为 LiteRT 或 CoreML,即可部署到 Android 或 iOS 设备。
    • 云端:利用 TensorFlow Serving 或 TorchServe 等框架,实现可扩展的云端部署。
    • Web:使用 ONNX Runtime Web 实现浏览器内推理。

    Ultralytics 提供导出函数,可将模型转换为各种格式以便部署。探索丰富的部署选项,找到最适合你使用场景的解决方案。

  • 主要区别包括:

    • 端到端无 NMS 推理:YOLO26 使用 nms=False 提供无 NMS 推理。默认的一对多路径使用 NMS 来提高准确率。
    • 移除 DFL:YOLO26 移除了分布焦点损失模块,简化了导出流程,并提升了与边缘设备和低功耗设备的兼容性。
    • MuSGD 优化器:结合 SGD 和 Muon 的混合优化器(灵感来自 Moonshot AI 的 Kimi K2),可实现更稳定的训练和更快的收敛。
    • CPU 性能:YOLO26n 在 CPU 上进行 ONNX 推理时,速度最高比 YOLO11n 快 43%(Intel Xeon CPU @ 2.00 GHz),非常适合没有 GPU 的设备。
    • 针对特定任务的优化:通过语义损失和多尺度原型增强分割效果;使用残差对数似然估计 (RLE) 提高姿态估计精度;通过角度损失改进 OBB 解码。
    • 任务:两个模型都支持目标检测和实例分割;YOLO26 还新增了用于密集像素级预测的语义分割和用于逐像素深度预测的单目深度估计。两个模型还通过统一框架支持分类、姿态估计和有向目标检测 (OBB)。

    如需深入比较功能和性能指标,请访问 YOLO26 文档页面。

  • 为 Ultralytics 做贡献是改进项目、拓展技能的好方法。你可以通过以下方式参与:

    1. 在 GitHub 上复刻 Ultralytics 仓库。
    2. 为你的功能或错误修复创建一个新分支。
    3. 进行修改,并确保所有测试都通过。
    4. 提交拉取请求,并清楚描述你的修改。
    5. 参与代码审查流程。

    你也可以通过报告错误、提出功能建议或改进文档来做贡献。有关详细指南和最佳实践,请参阅贡献指南。

  • Ultralytics YOLO 为高级计算机视觉任务提供了丰富的功能:

    • 实时检测:在实时场景中高效检测和分类目标。
    • 多任务能力:通过统一框架执行目标检测、实例分割、语义分割、单目深度估计、分类、姿态估计和定向目标检测 (OBB)。
    • 预训练模型:你可以使用多种预训练模型,在不同使用场景中平衡速度与准确率。
    • 自定义训练:借助灵活的训练流程,轻松使用自定义数据集微调模型。
    • 丰富的部署选项:将模型导出为 TensorRT、ONNX 和 CoreML 等多种格式,以便在不同平台上部署。
    • 全面的文档:借助详尽的文档和热心的社区,优化你的计算机视觉工作流。
  • 多种技术可以提升 YOLO 模型的性能:

    1. 超参数调优:参考超参数调优指南,尝试不同的超参数以优化模型性能。
    2. 数据增强:使用翻转、缩放、旋转和颜色调整等方法扩充训练数据集,提升模型的泛化能力。
    3. 迁移学习:利用预训练模型,并参考训练指南在特定数据集上进行微调。
    4. 导出为高效格式:参考导出指南,将模型转换为 TensorRT 或 ONNX 等优化格式,以加快推理速度。
    5. 基准测试:使用基准测试模式系统地衡量并提升推理速度和准确率。
  • Ultralytics 提供了丰富的资源,帮助你开始使用相关工具:

    • 官方文档:全面的指南、API 参考和最佳实践。
    • GitHub 仓库:源代码、示例脚本和社区贡献。
    • Ultralytics 博客:深入文章、应用案例和技术见解。
    • Ultralytics 学院:提供免费课程,涵盖计算机视觉基础知识、训练你的首个 YOLO 模型,以及在生产环境中运行 YOLO。
    • 社区论坛:与其他用户交流、提问并分享经验。
    • YouTube 频道:提供关于各种 Ultralytics 主题的视频教程、演示和网络研讨会。

    这些资源提供代码示例、实际使用案例和分步指南,介绍如何使用 Ultralytics 模型完成各种任务。

    如果你需要进一步帮助,请查阅 Ultralytics 文档,或通过 GitHub Issues 或官方讨论论坛联系社区。

评论154

提出问题、分享结果,或帮助其他人。

  1. oicoycGitHub

    Hello, I am really confused and unable to find a solution. I trained YOLOv8n on a dataset with 4000 images for 200 epochs, but during training, the mAP@50 never exceeded 0.4. However, when I use val.py or train.py to test the best.pt file again, the mAP@50 significantly increases to 0.7. Even if I retrain YOLOv8n, I can only get a poor result of 0.4, but this weight file consistently gives a result above 0.7 during testing. What could be the reason for this?

    1
    1. Glenn JocherUltralytics

      @oicoyc it seems like there might be a discrepancy between training and validation settings. Ensure that the dataset and parameters used during validation match those in training. For further insights, you can explore the FAQ section at Ultralytics Documentation.

    2. oicoycGitHub

      翻译如下:

      However, this best.pt consistently shows an mAP@50 above 0.6 on the same dataset, whether using train.py or val.py. But other weights or retraining the model that generated this weight file never achieve the same result, only reaching 0.4. Have you ever encountered this situation before?

    3. Glenn JocherUltralytics

      @oicoyc it sounds like there might be a difference in the evaluation settings or data splits between training and validation. Ensure consistency in dataset and parameters. For more insights, check the Ultralytics FAQ.

  2. arifan-instrumentasi-UBGitHub

    Hello, I am working with custom train yolo v8 model in Colab. I am using image as a source. How can I write a text on result image? I want to write the summary of prediction on the top of result image. Please help.

    1
    1. Glenn JocherUltralytics

      Hello! 😊

      To write a summary of your predictions on the top of your result image in Colab using a custom-trained YOLOv8 model, you can leverage the OpenCV library. Here's a quick example on how you can do that:

      import cv2
      
      # Assuming 'results' is your YOLOv8 model inference output
      # Load your image
      image = cv2.imread('path_to_your_image/image.jpg')
      
      # Define the text you want to add
      summary_text = "Your summary text here"
      
      # Set the position, font, scale, color, etc.
      position = (50, 50)  # Adjust based on your requirement
      font = cv2.FONT_HERSHEY_SIMPLEX
      font_scale = 1
      color = (255, 0, 0) # Blue color in BGR
      thickness = 2
      
      # Add the text to your image
      cv2.putText(image, summary_text, position, font, font_scale, color, thickness)
      
      # Save or display the result
      cv2.imwrite('path_to_save_image/summary_result.jpg', image)
      # or use cv2.imshow('Result', image) to display in Colab (might require additional setup for Colab)
      

      Make sure to adjust the path to your image, the summary_text content, and formatting options like position, font, fontScale, color, and thickness according to your preferences.

      Hope this helps! If you have any more questions, feel free to ask. Happy coding! 🚀

    2. arifan-instrumentasi-UBGitHub

      Hi, thanks for your help. But I have another question.

      the image variable in this line have file path. cv2.putText(image, summary_text, position, font, font_scale, color, thickness)

      how to call inference result to the image variable without file path (direct to inference result variable without saving the inference result before) ?

      thanks again, arifan

    3. Glenn JocherUltralytics(已编辑)

      Hi Arifan,

      Glad to help! 😊 To use the result of an inference directly without saving and reloading from a file path in OpenCV, you'll need to work directly with the image array returned by your YOLOv8 inference. After running an inference with your YOLO model, it typically returns an image tensor or array which you can convert to a format suitable for OpenCV operations. Here's a quick example:

      from ultralytics import YOLO
      
      # Assuming your model is loaded to 'model' and your image to infer is 'your_image'
      model = YOLO('your_model.pt')
      results = model('path/to/your_image.jpg')  # Perform inference
      
      # Get the annotated image as a NumPy array (BGR) for OpenCV
      inference_img = results[0].plot()
      
      # Now you can use cv2.putText directly on the 'inference_img'
      cv2.putText(inference_img, summary_text, position, font, font_scale, color, thickness)
      
      # Show or Save 'inference_img' as needed
      cv2.imshow('Inference Result with Text', inference_img)
      cv2.waitKey(0)
      cv2.destroyAllWindows()

      In this example, results[0].plot() returns the annotated image array of the first (or only) image predicted by the model, which you can then manipulate using OpenCV functions like cv2.putText directly without needing to save and reload the image from a path.

      Hope this clarifies things for you! Let me know if you have any more questions.

    4. Glenn JocherUltralytics(已编辑)

      Hi there! 👋 Glad to hear the previous advice was helpful for you.

      For processing a video file, the approach will be slightly different from handling a single image since you'll be working with a stream of frames rather than a static picture. You'll want to loop over each frame in the video, apply the detection, and then optionally write the text on each frame before displaying or saving it.

      Here's a simplified snippet to get you started:

      import cv2
      from ultralytics import YOLO
      
      # Load your custom-trained model
      model = YOLO('path/to/your_model.pt')
      
      # Initialize video capture from a file
      cap = cv2.VideoCapture('path/to/your_video.mp4')
      
      while cap.isOpened():
          ret, frame = cap.read()
          if not ret:
              break
      
          # Run model inference on the current frame
          results = model(frame)
          frame = results[0].plot()  # draw the detections on the frame
      
          # [Optional] Customize this part to add your summary text to each frame
          cv2.putText(frame, 'Your summary text here', (50, 50), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 0, 0), 2)
      
          # Display the frame
          cv2.imshow('Frame', frame)
      
          if cv2.waitKey(1) & 0xFF == ord('q'): # Press 'q' to quit
              break
      
      cap.release()
      cv2.destroyAllWindows()

      Make sure to adjust the paths, model, and summary text as needed. This code assumes you're working within an environment that supports OpenCV displays (like Jupyter or running locally).

      For real-time performance or handling larger videos, consider optimizations 🚀 such as reducing imgsz for faster processing or using a more powerful GPU.

    5. Glenn JocherUltralytics

      Hi there! 😊

      Yes, you're exactly right! For adding text to your video frames, you'll directly work with the frame obtained from cap.read() rather than the inference result. Here's how you can do it:

      # Example code snippet
      import cv2
      cap = cv2.VideoCapture('path/to/your_video.mp4')
      
      while True:
          ret, frame = cap.read()
          if not ret:
              break
      
          # Place your text on the frame here
          cv2.putText(frame, "Your Text Here", (10,30), cv2.FONT_HERSHEY_SIMPLEX, 1, (255,255,255), 2)
      
          # Show the frame
          cv2.imshow('Frame', frame)
      
          if cv2.waitKey(1) & 0xFF == ord('q'):
              break
      
      cap.release()
      cv2.destroyAllWindows()

      This approach lets you dynamically display information directly on the video stream. 📹 If you have more questions or need further assistance, feel free to ask. Happy coding!

  3. oukkaheGitHub

    Hi Paula!

    I have not reported anything for months now.

    I do not understand what this is about.

    BR,

    Heikki

    From: Paula Derrenger @.> Sent: Monday, 24 August 2026 13.36 To: ultralytics/ultralytics @.> Cc: oukkahe @.>; Comment @.> Subject: Re: [ultralytics/ultralytics] help/FAQ/ (Discussion #7928)

    Please share the exact upload/training error and your dataset structure. Segmentation labels must follow the Ultralytics segmentation dataset format https://docs.ultralytics.com/datasets/segment , with one matching .txt file per image containing normalized polygon coordinates and at least three points per object; please continue posting details here so the Ultralytics team can investigate.

    — Reply to this email directly, view it on GitHub https://github.com/orgs/ultralytics/discussions/7928?email_source=notifications&email_token=AFVEEPWRWQTVMISQRP7QBFT5LQLBFA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBRGMZTQMBZUZZGKYLTN5XKOY3PNVWWK3TUUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#discussioncomment-18133809 , or unsubscribe https://github.com/notifications/unsubscribe-auth/AFVEEPWBYBSTVGYGSCVFGRL5LQLBFAVCNFSNUABHKJSXA33TNF2G64TZHM2TGNJTGYYDINBVHNCGS43DOVZXG2LPNY5TMMJWGEYTKONBOYBA . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS https://github.com/notifications/mobile/ios/AFVEEPSGHO5VYLT4OEILRNL5LQLBFA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBRGMZTQMBZUZZGKYLTN5XKOY3PNVWWK3TUUVSXMZLOOSVGM33PORSXEX3JN5ZQ and Android https://github.com/notifications/mobile/android/AFVEEPQNNBDUPPWWHNQECST5LQLBFA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBRGMZTQMBZUZZGKYLTN5XKOY3PNVWWK3TUUVSXMZLOOSXGM33PORSXEX3BNZSHE33JMQ . Download it today! You are receiving this because you commented. https://github.com/notifications/beacon/AFVEEPVFS7CXU7IMCBMQ3ZD5LQLBFBFCNFSM6AAAAAC6DDWSKOWGG33NNVSW45C7OR4XAZNRIRUXGY3VONZWS33OINXW23LFNZ2KUY3PNVWWK3TUL5UWJTQBCSZTDJTSMVQXG33OU5RW63LNMVXHI.gif Message ID: @.*** @.***> >

  4. User

    Why can't my segmentation be uploaded in the model? It's impossible to conduct training.

    1. Paula DerrengerUltralytics

      Please share the exact upload/training error and your dataset structure. Segmentation labels must follow the Ultralytics segmentation dataset format, with one matching .txt file per image containing normalized polygon coordinates and at least three points per object; please continue posting details here so the Ultralytics team can investigate.

  5. oukkaheGitHub

    Hello Ultralytics! Keep up the good work. I am wondering if there is any support or sample code for using Yolo11 with openVino in c++? I am aware of Python openVino support. Something like that for c++ would be great.

    1. Glenn JocherUltralytics

      We don’t currently maintain an official Ultralytics C++ OpenVINO inference sample in this repo; the recommended workflow is to export your YOLO11 model to OpenVINO IR using our OpenVINO integration docs and then run it with the native OpenVINO C++ runtime (you’ll need to implement YOLO11 pre/post-processing in C++, including NMS—if you want a simpler end-to-end export path, consider Ultralytics YOLO26).

      yolo export model=yolo11n.pt format=openvino
  6. Narayanan-nansGitHub

    Hi Team, Thanks for doing great works in the computer vision field. I want to know whether do you have any idea to integrate cupy with ultralytics packages in place of numpy & scipy, If you do have when can we expect the same to be integrated? Thanks in advance

  7. ralekzGitHub

    Hi! Your neural network claims that your Yolo11 models come with feature map stride parameters of 32, 16, and 8. How can I also get your detection models with feature map stride = 4? Can I download the entire line of detection models with this parameter? Can I change this parameter myself? I need to predict small details with greater accuracy...

    1. Glenn JocherUltralytics

      @ralekz you’re right that the standard YOLO11 detection models use 8/16/32 strides, and we don’t currently publish a variant with a stride‑4 detection head, so there’s nothing to “just download” for that. To get stride 4 you’d need to modify the model YAML (add an extra low‑stride feature map / detection head) and then train or fine‑tune that custom architecture; simply changing a stride value on an existing .pt without retraining is not supported and will generally degrade performance. For an overview of how the YOLO11 backbone and head are defined so you can experiment safely, see the YOLO11 model page and its links to configuration details.

      1
  8. ralekzGitHub

    Hi, thank you for your support! I can't figure out how to further train my YOLO 11 model. For example, I have a dataset of 150,000 labeled images of Toyota cars, and it works perfectly. But in the new year, a new model is released, and the old ones have been restyled. How can I add predictive capabilities to my model for these new and updated models without losing the previous training skills? Is it really only possible to use a combined dataset?

    1. ralekzGitHub

      That moment when I sewed my own severed arms back on with my own feet... Give me back my thanks.

    2. Glenn JocherUltralytics(已编辑)

      @alexs-rufer the self.hyp.box error means the internal detection model hasn’t had its training hyperparameters (hyp) initialized into the object the loss expects; that setup is normally done only when you go through the built‑in model.train(...) / Trainer pipeline, which then calls self.model(batch) for you. Directly calling model.model(batch) is therefore using internal APIs that assume the Trainer has already populated self.hyp and the loss object, so things break when you bypass it. For a stable solution, I’d recommend basing your Active Teacher loop on the existing detection trainer (copying or subclassing it and overriding the training step) rather than calling model.model(batch) in isolation; the reference implementation in ultralytics/models/yolo/detect/train.py shows exactly how the batch dict and loss forward are wired together.

      @barath38 to get very accurate box/segment predictions for your 3D coordinate use case, focus first on having perfectly drawn masks/boxes and training data that really matches your deployment setup (same camera height, distance, row/column layout, and lighting), rather than just collecting thousands of random box images. A few hundred well‑annotated examples per box type and viewpoint, combined with strong augmentation (rotations, perspective changes, zoom, brightness/contrast) usually gives better results than many near‑duplicate images; you can also crop around the grid so each box is larger in the frame, which helps both segmentation quality and depth stability. For concrete guidance on how much data and what variety to target, see the Data Collection and Annotation guide together with the Preprocessing annotated data guide.

      @sarath-knackforge there’s no supported way to “merge” two YOLOv8 checkpoints into a single model in a clean, automatic way; in practice you either retrain one model on a combined dataset (license-plate data plus your custom data, with a unified label set) or you keep two separate models and run them sequentially in your pipeline. If you go with the single-model approach, just merge the datasets and train one YOLO model as usual; the object-detection docs at the YOLO detection task page show how to structure multi-class datasets for this.

      @ralekz no worries on the earlier comment—on the technical side, if you want your YOLO11 model to keep performing well on the existing Toyota models while learning the new and restyled ones, you do need to keep training on some mix of old and new data; training only on the new models will typically cause forgetting of the older variants. You don’t have to keep all 150k old images in the loop, but sampling a representative subset and mixing them with the new-model images, then fine‑tuning from your current best.pt, is the standard way to extend the model without losing past knowledge. Longer term, treating this as a recurring maintenance process—periodically adding new data, rebalancing the mix, and re‑validating—is best practice; the guide on maintaining your computer vision models after deployment walks through that workflow in more detail.

      1
  9. sarath-knackforgeGitHub

    Hi team, i have one doubt , i already done research in online but i didn't get proper finalized answer. i want to merge two separate model into single model , i want to merge yolo8 licence plate detection model with my custome fine tune model ( used yolo8s.pt pretrained model to train), so can i able to merge both modle into single mode ?

    Thank you.