Bỏ để qua phần nội dung

Tài liệu tham khảo cho ultralytics/hub/utils.py

Ghi

Tệp này có sẵn tại https://github.com/ultralytics/ultralytics/blob/main/ultralytics/hub/utils.py. Nếu bạn phát hiện ra một vấn đề, vui lòng giúp khắc phục nó bằng cách đóng góp Yêu cầu 🛠️ kéo. Cảm ơn bạn 🙏 !



ultralytics.hub.utils.Events

Một lớp học để thu thập phân tích sự kiện ẩn danh. Phân tích sự kiện được bật khi sync=True trong cài đặt và bị vô hiệu hóa khi sync = False. Chạy 'yolo cài đặt 'để xem và cập nhật cài đặt tệp YAML.

Thuộc tính:

Tên Kiểu Sự miêu tả
url str

URL để gửi sự kiện ẩn danh.

rate_limit float

Giới hạn tốc độ tính bằng giây để gửi sự kiện.

metadata dict

Một từ điển chứa siêu dữ liệu về môi trường.

enabled bool

Cờ để bật hoặc tắt Sự kiện dựa trên một số điều kiện nhất định.

Mã nguồn trong ultralytics/hub/utils.py
class Events:
    """
    A class for collecting anonymous event analytics. Event analytics are enabled when sync=True in settings and
    disabled when sync=False. Run 'yolo settings' to see and update settings YAML file.

    Attributes:
        url (str): The URL to send anonymous events.
        rate_limit (float): The rate limit in seconds for sending events.
        metadata (dict): A dictionary containing metadata about the environment.
        enabled (bool): A flag to enable or disable Events based on certain conditions.
    """

    url = "https://www.google-analytics.com/mp/collect?measurement_id=G-X8NCJYTQXM&api_secret=QLQrATrNSwGRFRLE-cbHJw"

    def __init__(self):
        """Initializes the Events object with default values for events, rate_limit, and metadata."""
        self.events = []  # events list
        self.rate_limit = 60.0  # rate limit (seconds)
        self.t = 0.0  # rate limit timer (seconds)
        self.metadata = {
            "cli": Path(ARGV[0]).name == "yolo",
            "install": "git" if IS_GIT_DIR else "pip" if IS_PIP_PACKAGE else "other",
            "python": ".".join(platform.python_version_tuple()[:2]),  # i.e. 3.10
            "version": __version__,
            "env": ENVIRONMENT,
            "session_id": round(random.random() * 1e15),
            "engagement_time_msec": 1000,
        }
        self.enabled = (
            SETTINGS["sync"]
            and RANK in {-1, 0}
            and not TESTS_RUNNING
            and ONLINE
            and (IS_PIP_PACKAGE or get_git_origin_url() == "https://github.com/ultralytics/ultralytics.git")
        )

    def __call__(self, cfg):
        """
        Attempts to add a new event to the events list and send events if the rate limit is reached.

        Args:
            cfg (IterableSimpleNamespace): The configuration object containing mode and task information.
        """
        if not self.enabled:
            # Events disabled, do nothing
            return

        # Attempt to add to events
        if len(self.events) < 25:  # Events list limited to 25 events (drop any events past this)
            params = {
                **self.metadata,
                "task": cfg.task,
                "model": cfg.model if cfg.model in GITHUB_ASSETS_NAMES else "custom",
            }
            if cfg.mode == "export":
                params["format"] = cfg.format
            self.events.append({"name": cfg.mode, "params": params})

        # Check rate limit
        t = time.time()
        if (t - self.t) < self.rate_limit:
            # Time is under rate limiter, wait to send
            return

        # Time is over rate limiter, send now
        data = {"client_id": SETTINGS["uuid"], "events": self.events}  # SHA-256 anonymized UUID hash and events list

        # POST equivalent to requests.post(self.url, json=data)
        smart_request("post", self.url, json=data, retry=0, verbose=False)

        # Reset events and rate limit timer
        self.events = []
        self.t = t

__call__(cfg)

Cố gắng thêm sự kiện mới vào danh sách sự kiện và gửi sự kiện nếu đạt đến giới hạn tốc độ.

Thông số:

Tên Kiểu Sự miêu tả Mặc định
cfg IterableSimpleNamespace

Đối tượng cấu hình chứa chế độ và thông tin tác vụ.

bắt buộc
Mã nguồn trong ultralytics/hub/utils.py
def __call__(self, cfg):
    """
    Attempts to add a new event to the events list and send events if the rate limit is reached.

    Args:
        cfg (IterableSimpleNamespace): The configuration object containing mode and task information.
    """
    if not self.enabled:
        # Events disabled, do nothing
        return

    # Attempt to add to events
    if len(self.events) < 25:  # Events list limited to 25 events (drop any events past this)
        params = {
            **self.metadata,
            "task": cfg.task,
            "model": cfg.model if cfg.model in GITHUB_ASSETS_NAMES else "custom",
        }
        if cfg.mode == "export":
            params["format"] = cfg.format
        self.events.append({"name": cfg.mode, "params": params})

    # Check rate limit
    t = time.time()
    if (t - self.t) < self.rate_limit:
        # Time is under rate limiter, wait to send
        return

    # Time is over rate limiter, send now
    data = {"client_id": SETTINGS["uuid"], "events": self.events}  # SHA-256 anonymized UUID hash and events list

    # POST equivalent to requests.post(self.url, json=data)
    smart_request("post", self.url, json=data, retry=0, verbose=False)

    # Reset events and rate limit timer
    self.events = []
    self.t = t

__init__()

Khởi tạo đối tượng Events với các giá trị mặc định cho events, rate_limit và metadata.

Mã nguồn trong ultralytics/hub/utils.py
def __init__(self):
    """Initializes the Events object with default values for events, rate_limit, and metadata."""
    self.events = []  # events list
    self.rate_limit = 60.0  # rate limit (seconds)
    self.t = 0.0  # rate limit timer (seconds)
    self.metadata = {
        "cli": Path(ARGV[0]).name == "yolo",
        "install": "git" if IS_GIT_DIR else "pip" if IS_PIP_PACKAGE else "other",
        "python": ".".join(platform.python_version_tuple()[:2]),  # i.e. 3.10
        "version": __version__,
        "env": ENVIRONMENT,
        "session_id": round(random.random() * 1e15),
        "engagement_time_msec": 1000,
    }
    self.enabled = (
        SETTINGS["sync"]
        and RANK in {-1, 0}
        and not TESTS_RUNNING
        and ONLINE
        and (IS_PIP_PACKAGE or get_git_origin_url() == "https://github.com/ultralytics/ultralytics.git")
    )



ultralytics.hub.utils.request_with_credentials(url)

Thực hiện yêu cầu AJAX với cookie được đính kèm trong môi trường Google Colab.

Thông số:

Tên Kiểu Sự miêu tả Mặc định
url str

URL để thực hiện yêu cầu.

bắt buộc

Trở lại:

Kiểu Sự miêu tả
any

Dữ liệu phản hồi từ yêu cầu AJAX.

Tăng:

Kiểu Sự miêu tả
OSError

Nếu hàm không được chạy trong môi trường Google Colab.

Mã nguồn trong ultralytics/hub/utils.py
def request_with_credentials(url: str) -> any:
    """
    Make an AJAX request with cookies attached in a Google Colab environment.

    Args:
        url (str): The URL to make the request to.

    Returns:
        (any): The response data from the AJAX request.

    Raises:
        OSError: If the function is not run in a Google Colab environment.
    """
    if not IS_COLAB:
        raise OSError("request_with_credentials() must run in a Colab environment")
    from google.colab import output  # noqa
    from IPython import display  # noqa

    display.display(
        display.Javascript(
            """
            window._hub_tmp = new Promise((resolve, reject) => {
                const timeout = setTimeout(() => reject("Failed authenticating existing browser session"), 5000)
                fetch("%s", {
                    method: 'POST',
                    credentials: 'include'
                })
                    .then((response) => resolve(response.json()))
                    .then((json) => {
                    clearTimeout(timeout);
                    }).catch((err) => {
                    clearTimeout(timeout);
                    reject(err);
                });
            });
            """
            % url
        )
    )
    return output.eval_js("_hub_tmp")



ultralytics.hub.utils.requests_with_progress(method, url, **kwargs)

Thực hiện yêu cầu HTTP bằng phương thức và URL được chỉ định, với thanh tiến trình tùy chọn.

Thông số:

Tên Kiểu Sự miêu tả Mặc định
method str

Phương thức HTTP để sử dụng (ví dụ: 'GET', 'POST').

bắt buộc
url str

URL để gửi yêu cầu đến.

bắt buộc
**kwargs any

Các đối số từ khóa bổ sung để chuyển đến bên dưới requests.request chức năng.

{}

Trở lại:

Kiểu Sự miêu tả
Response

Đối tượng phản hồi từ yêu cầu HTTP.

Ghi
  • Nếu 'tiến trình' được đặt thành True, thanh tiến trình sẽ hiển thị tiến trình tải xuống cho các câu trả lời với một câu trả lời đã biết độ dài nội dung.
  • Nếu 'tiến trình' là một số thì thanh tiến trình sẽ hiển thị giả định độ dài nội dung = tiến trình.
Mã nguồn trong ultralytics/hub/utils.py
def requests_with_progress(method, url, **kwargs):
    """
    Make an HTTP request using the specified method and URL, with an optional progress bar.

    Args:
        method (str): The HTTP method to use (e.g. 'GET', 'POST').
        url (str): The URL to send the request to.
        **kwargs (any): Additional keyword arguments to pass to the underlying `requests.request` function.

    Returns:
        (requests.Response): The response object from the HTTP request.

    Note:
        - If 'progress' is set to True, the progress bar will display the download progress for responses with a known
        content length.
        - If 'progress' is a number then progress bar will display assuming content length = progress.
    """
    progress = kwargs.pop("progress", False)
    if not progress:
        return requests.request(method, url, **kwargs)
    response = requests.request(method, url, stream=True, **kwargs)
    total = int(response.headers.get("content-length", 0) if isinstance(progress, bool) else progress)  # total size
    try:
        pbar = TQDM(total=total, unit="B", unit_scale=True, unit_divisor=1024)
        for data in response.iter_content(chunk_size=1024):
            pbar.update(len(data))
        pbar.close()
    except requests.exceptions.ChunkedEncodingError:  # avoid 'Connection broken: IncompleteRead' warnings
        response.close()
    return response



ultralytics.hub.utils.smart_request(method, url, retry=3, timeout=30, thread=True, code=-1, verbose=True, progress=False, **kwargs)

Thực hiện yêu cầu HTTP bằng cách sử dụng thư viện 'yêu cầu', với các lần thử lùi theo cấp số nhân lên đến một thời gian chờ được chỉ định.

Thông số:

Tên Kiểu Sự miêu tả Mặc định
method str

Phương thức HTTP để sử dụng cho yêu cầu. Lựa chọn là 'đăng' và 'nhận'.

bắt buộc
url str

URL để thực hiện yêu cầu.

bắt buộc
retry int

Số lần thử lại để thử trước khi bỏ cuộc. Mặc định là 3.

3
timeout int

Thời gian chờ trong vài giây sau đó chức năng sẽ từ bỏ thử lại. Mặc định là 30.

30
thread bool

Có nên thực hiện yêu cầu trong một luồng daemon riêng biệt hay không. Mặc định là True.

True
code int

Một mã định danh cho yêu cầu, được sử dụng cho mục đích ghi nhật ký. Mặc định là -1.

-1
verbose bool

Một lá cờ để xác định xem có nên in ra để điều khiển hay không. Mặc định là True.

True
progress bool

Có hiển thị thanh tiến trình trong khi yêu cầu hay không. Mặc định là False.

False
**kwargs any

Các đối số từ khóa sẽ được chuyển đến hàm yêu cầu được chỉ định trong phương thức.

{}

Trở lại:

Kiểu Sự miêu tả
Response

Đối tượng phản hồi HTTP. Nếu yêu cầu được thực thi trong một luồng riêng biệt, trả về Không có.

Mã nguồn trong ultralytics/hub/utils.py
def smart_request(method, url, retry=3, timeout=30, thread=True, code=-1, verbose=True, progress=False, **kwargs):
    """
    Makes an HTTP request using the 'requests' library, with exponential backoff retries up to a specified timeout.

    Args:
        method (str): The HTTP method to use for the request. Choices are 'post' and 'get'.
        url (str): The URL to make the request to.
        retry (int, optional): Number of retries to attempt before giving up. Default is 3.
        timeout (int, optional): Timeout in seconds after which the function will give up retrying. Default is 30.
        thread (bool, optional): Whether to execute the request in a separate daemon thread. Default is True.
        code (int, optional): An identifier for the request, used for logging purposes. Default is -1.
        verbose (bool, optional): A flag to determine whether to print out to console or not. Default is True.
        progress (bool, optional): Whether to show a progress bar during the request. Default is False.
        **kwargs (any): Keyword arguments to be passed to the requests function specified in method.

    Returns:
        (requests.Response): The HTTP response object. If the request is executed in a separate thread, returns None.
    """
    retry_codes = (408, 500)  # retry only these codes

    @TryExcept(verbose=verbose)
    def func(func_method, func_url, **func_kwargs):
        """Make HTTP requests with retries and timeouts, with optional progress tracking."""
        r = None  # response
        t0 = time.time()  # initial time for timer
        for i in range(retry + 1):
            if (time.time() - t0) > timeout:
                break
            r = requests_with_progress(func_method, func_url, **func_kwargs)  # i.e. get(url, data, json, files)
            if r.status_code < 300:  # return codes in the 2xx range are generally considered "good" or "successful"
                break
            try:
                m = r.json().get("message", "No JSON message.")
            except AttributeError:
                m = "Unable to read JSON."
            if i == 0:
                if r.status_code in retry_codes:
                    m += f" Retrying {retry}x for {timeout}s." if retry else ""
                elif r.status_code == 429:  # rate limit
                    h = r.headers  # response headers
                    m = (
                        f"Rate limit reached ({h['X-RateLimit-Remaining']}/{h['X-RateLimit-Limit']}). "
                        f"Please retry after {h['Retry-After']}s."
                    )
                if verbose:
                    LOGGER.warning(f"{PREFIX}{m} {HELP_MSG} ({r.status_code} #{code})")
                if r.status_code not in retry_codes:
                    return r
            time.sleep(2**i)  # exponential standoff
        return r

    args = method, url
    kwargs["progress"] = progress
    if thread:
        threading.Thread(target=func, args=args, kwargs=kwargs, daemon=True).start()
    else:
        return func(*args, **kwargs)





Created 2023-11-12, Updated 2024-06-02
Authors: glenn-jocher (5), Burhan-Q (1)