์ฝ˜ํ…์ธ ๋กœ ๊ฑด๋„ˆ๋›ฐ๊ธฐ

์ฐธ์กฐ ultralytics/hub/utils.py

์ฐธ๊ณ 

์ด ํŒŒ์ผ์€ https://github.com/ultralytics/ ultralytics/blob/main/ ultralytics/hub/utils .py์—์„œ ํ™•์ธํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ฌธ์ œ๋ฅผ ๋ฐœ๊ฒฌํ•˜๋ฉด ํ’€ ๋ฆฌํ€˜์ŠคํŠธ (๐Ÿ› ๏ธ) ๋ฅผ ํ†ตํ•ด ๋ฌธ์ œ๋ฅผ ํ•ด๊ฒฐํ•˜๋„๋ก ๋„์™€์ฃผ์„ธ์š”. ๊ฐ์‚ฌํ•ฉ๋‹ˆ๋‹ค ๐Ÿ™!



ultralytics.hub.utils.Events

์ต๋ช… ์ด๋ฒคํŠธ ๋ถ„์„ ์ˆ˜์ง‘์„ ์œ„ํ•œ ํด๋ž˜์Šค์ž…๋‹ˆ๋‹ค. ์ด๋ฒคํŠธ ๋ถ„์„์€ ์„ค์ •์—์„œ sync=False์ผ ๋•Œ ํ™œ์„ฑํ™”๋˜๊ณ  sync=False์ด๋ฉด ๋น„ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค. 'yolo settings'๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ์„ค์ • YAML ํŒŒ์ผ์„ ํ™•์ธํ•˜๊ณ  ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค.

์†์„ฑ:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช…
url str

์ต๋ช… ์ด๋ฒคํŠธ๋ฅผ ์ „์†กํ•  URL์ž…๋‹ˆ๋‹ค.

rate_limit float

์ด๋ฒคํŠธ ์ „์†ก์— ๋Œ€ํ•œ ์ดˆ ๋‹จ์œ„ ์†๋„ ์ œํ•œ์ž…๋‹ˆ๋‹ค.

metadata dict

ํ™˜๊ฒฝ์— ๋Œ€ํ•œ ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ๊ฐ€ ํฌํ•จ๋œ ์‚ฌ์ „์ž…๋‹ˆ๋‹ค.

enabled bool

ํŠน์ • ์กฐ๊ฑด์— ๋”ฐ๋ผ ์ด๋ฒคํŠธ๋ฅผ ํ™œ์„ฑํ™” ๋˜๋Š” ๋น„ํ™œ์„ฑํ™”ํ•˜๋Š” ํ”Œ๋ž˜๊ทธ์ž…๋‹ˆ๋‹ค.

์˜ ์†Œ์Šค ์ฝ”๋“œ 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)

์ด๋ฒคํŠธ ๋ชฉ๋ก์— ์ƒˆ ์ด๋ฒคํŠธ๋ฅผ ์ถ”๊ฐ€ํ•˜๊ณ  ์š”๊ธˆ ํ•œ๋„์— ๋„๋‹ฌํ•˜๋ฉด ์ด๋ฒคํŠธ๋ฅผ ๋ณด๋‚ด๋ ค๊ณ  ์‹œ๋„ํ•ฉ๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช… ๊ธฐ๋ณธ๊ฐ’
cfg IterableSimpleNamespace

๋ชจ๋“œ ๋ฐ ์ž‘์—… ์ •๋ณด๊ฐ€ ํฌํ•จ๋œ ๊ตฌ์„ฑ ๊ฐœ์ฒด์ž…๋‹ˆ๋‹ค.

ํ•„์ˆ˜
์˜ ์†Œ์Šค ์ฝ”๋“œ 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__()

์ด๋ฒคํŠธ, rate_limit ๋ฐ ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ์— ๋Œ€ํ•œ ๊ธฐ๋ณธ๊ฐ’์œผ๋กœ ์ด๋ฒคํŠธ ๊ฐ์ฒด๋ฅผ ์ดˆ๊ธฐํ™”ํ•ฉ๋‹ˆ๋‹ค.

์˜ ์†Œ์Šค ์ฝ”๋“œ 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)

Google Colab ํ™˜๊ฒฝ์—์„œ ์ฟ ํ‚ค๋ฅผ ์ฒจ๋ถ€ํ•˜์—ฌ AJAX ์š”์ฒญ์„ ํ•ฉ๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช… ๊ธฐ๋ณธ๊ฐ’
url str

์š”์ฒญํ•  URL์ž…๋‹ˆ๋‹ค.

ํ•„์ˆ˜

๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค:

์œ ํ˜• ์„ค๋ช…
any

AJAX ์š”์ฒญ์˜ ์‘๋‹ต ๋ฐ์ดํ„ฐ์ž…๋‹ˆ๋‹ค.

์˜ฌ๋ฆฌ๋‹ค:

์œ ํ˜• ์„ค๋ช…
OSError

์ด ํ•จ์ˆ˜๊ฐ€ Google Colab ํ™˜๊ฒฝ์—์„œ ์‹คํ–‰๋˜์ง€ ์•Š๋Š” ๊ฒฝ์šฐ.

์˜ ์†Œ์Šค ์ฝ”๋“œ 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)

์ง€์ •๋œ ๋ฐฉ๋ฒ•๊ณผ URL์„ ์‚ฌ์šฉํ•˜์—ฌ HTTP ์š”์ฒญ์„ ํ•˜๊ณ  ์ง„ํ–‰๋ฅ  ํ‘œ์‹œ์ค„(์„ ํƒ ์‚ฌํ•ญ)์„ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช… ๊ธฐ๋ณธ๊ฐ’
method str

์‚ฌ์šฉํ•  HTTP ๋ฉ”์„œ๋“œ(์˜ˆ: 'GET', 'POST').

ํ•„์ˆ˜
url str

์š”์ฒญ์„ ๋ณด๋‚ผ URL์ž…๋‹ˆ๋‹ค.

ํ•„์ˆ˜
**kwargs any

๊ธฐ๋ณธ ํ‚ค์›Œ๋“œ ์ธ์ž๋กœ ์ „๋‹ฌํ•  ์ถ”๊ฐ€ ํ‚ค์›Œ๋“œ ์ธ์ž requests.request ํ•จ์ˆ˜์ž…๋‹ˆ๋‹ค.

{}

๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค:

์œ ํ˜• ์„ค๋ช…
Response

HTTP ์š”์ฒญ์˜ ์‘๋‹ต ๊ฐ์ฒด์ž…๋‹ˆ๋‹ค.

์ฐธ๊ณ 
  • '์ง„ํ–‰ ์ค‘'์ด True๋กœ ์„ค์ •๋˜์–ด ์žˆ์œผ๋ฉด ์ง„ํ–‰๋ฅ  ํ‘œ์‹œ์ค„์— ์•Œ๋ ค์ง„ ์ฝ˜ํ…์ธ  ๊ธธ์ด๋ฅผ ๊ฐ€์ง„ ์‘๋‹ต์˜ ๋‹ค์šด๋กœ๋“œ ์ง„ํ–‰๋ฅ ์ด ์ฝ˜ํ…์ธ  ๊ธธ์ด๋ฅผ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค.
  • '์ง„ํ–‰๋ฅ '์ด ์ˆซ์ž์ธ ๊ฒฝ์šฐ ์ฝ˜ํ…์ธ  ๊ธธ์ด = ์ง„ํ–‰๋ฅ ๋กœ ๊ฐ€์ •ํ•˜์—ฌ ์ง„ํ–‰๋ฅ  ํ‘œ์‹œ์ค„์ด ํ‘œ์‹œ๋ฉ๋‹ˆ๋‹ค.
์˜ ์†Œ์Šค ์ฝ”๋“œ 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)

์ง€์ •๋œ ์‹œ๊ฐ„ ์ดˆ๊ณผ๊นŒ์ง€ ๊ธฐํ•˜๊ธ‰์ˆ˜์ ์œผ๋กœ ๋ฐฑ์˜คํ”„๋ฅผ ์žฌ์‹œ๋„ํ•˜๋Š” '์š”์ฒญ' ๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ HTTP ์š”์ฒญ์„ ํ•ฉ๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช… ๊ธฐ๋ณธ๊ฐ’
method str

์š”์ฒญ์— ์‚ฌ์šฉํ•  HTTP ๋ฉ”์„œ๋“œ์ž…๋‹ˆ๋‹ค. ์„ ํƒ ๊ฐ€๋Šฅํ•œ ๋ฉ”์„œ๋“œ๋Š” 'post'์™€ 'get'์ž…๋‹ˆ๋‹ค.

ํ•„์ˆ˜
url str

์š”์ฒญํ•  URL์ž…๋‹ˆ๋‹ค.

ํ•„์ˆ˜
retry int

ํฌ๊ธฐํ•˜๊ธฐ ์ „์— ์‹œ๋„ํ•  ์ˆ˜ ์žˆ๋Š” ์žฌ์‹œ๋„ ํšŸ์ˆ˜์ž…๋‹ˆ๋‹ค. ๊ธฐ๋ณธ๊ฐ’์€ 3์ž…๋‹ˆ๋‹ค.

3
timeout int

๊ธฐ๋Šฅ์ด ์žฌ์‹œ๋„๋ฅผ ํฌ๊ธฐํ•˜๋Š” ์‹œ๊ฐ„(์ดˆ)์ž…๋‹ˆ๋‹ค. ๊ธฐ๋ณธ๊ฐ’์€ 30์ดˆ์ž…๋‹ˆ๋‹ค.

30
thread bool

๋ณ„๋„์˜ ๋ฐ๋ชฌ ์Šค๋ ˆ๋“œ์—์„œ ์š”์ฒญ์„ ์‹คํ–‰ํ• ์ง€ ์—ฌ๋ถ€์ž…๋‹ˆ๋‹ค. ๊ธฐ๋ณธ๊ฐ’์€ True์ž…๋‹ˆ๋‹ค.

True
code int

๋กœ๊น… ๋ชฉ์ ์œผ๋กœ ์‚ฌ์šฉ๋˜๋Š” ์š”์ฒญ์˜ ์‹๋ณ„์ž์ž…๋‹ˆ๋‹ค. ๊ธฐ๋ณธ๊ฐ’์€ -1์ž…๋‹ˆ๋‹ค.

-1
verbose bool

์ฝ˜์†”์— ์ถœ๋ ฅํ• ์ง€ ์—ฌ๋ถ€๋ฅผ ๊ฒฐ์ •ํ•˜๋Š” ํ”Œ๋ž˜๊ทธ์ž…๋‹ˆ๋‹ค. ๊ธฐ๋ณธ๊ฐ’์€ True์ž…๋‹ˆ๋‹ค.

True
progress bool

์š”์ฒญ ์ค‘ ์ง„ํ–‰๋ฅ  ํ‘œ์‹œ์ค„์„ ํ‘œ์‹œํ• ์ง€ ์—ฌ๋ถ€์ž…๋‹ˆ๋‹ค. ๊ธฐ๋ณธ๊ฐ’์€ False์ž…๋‹ˆ๋‹ค.

False
**kwargs any

๋ฉ”์„œ๋“œ์— ์ง€์ •๋œ ์š”์ฒญ ํ•จ์ˆ˜์— ์ „๋‹ฌํ•  ํ‚ค์›Œ๋“œ ์ธ์ˆ˜์ž…๋‹ˆ๋‹ค.

{}

๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค:

์œ ํ˜• ์„ค๋ช…
Response

HTTP ์‘๋‹ต ๊ฐ์ฒด์ž…๋‹ˆ๋‹ค. ์š”์ฒญ์ด ๋ณ„๋„์˜ ์Šค๋ ˆ๋“œ์—์„œ ์‹คํ–‰๋˜๋Š” ๊ฒฝ์šฐ None์„ ๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค.

์˜ ์†Œ์Šค ์ฝ”๋“œ 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)