本地

這包含 TorchX 本地排程器，可用於透過子程序在本地執行 TorchX 元件。

類別 torchx.schedulers.local_scheduler.LocalScheduler(session_name: str, image_provider_class: Callable[[LocalOpts], ImageProvider], cache_size: int = 100, extra_paths: Optional[List[str]] = None)

基底： Scheduler[LocalOpts]

在本地主機上排程。容器被建模為程序，並且容器的某些屬性（如果與本地主機執行無關或無法強制執行）將被忽略。被忽略的屬性

1. 資源需求

2. 資源限制強制執行

3. 重試策略

4. 重試次數（不支援重試）

5. 部署偏好設定

排程器支援在收到 SIGTERM 或 SIGINT 時清除孤立程序。排程器將終止產生的程序。

這是透過排程器 local_cwd 公開的。

• local_cwd 會相對於目前的工作目錄執行提供的應用程式，並忽略 images 欄位，以便更快地進行迭代和測試。

注意

只有從主執行緒實例化 LocalScheduler 時，孤立程序清除才有效。

設定選項

    usage:
        [log_dir=LOG_DIR],[prepend_cwd=PREPEND_CWD],[auto_set_cuda_visible_devices=AUTO_SET_CUDA_VISIBLE_DEVICES]

    optional arguments:
        log_dir=LOG_DIR (str, None)
            dir to write stdout/stderr log files of replicas
        prepend_cwd=PREPEND_CWD (bool, False)
            if set, prepends CWD to replica's PATH env var making any binaries in CWD take precedence over those in PATH
        auto_set_cuda_visible_devices=AUTO_SET_CUDA_VISIBLE_DEVICES (bool, False)
            sets the `CUDA_AVAILABLE_DEVICES` for roles that request GPU resources. Each role replica will be assigned one GPU. Does nothing if the device count is less than replicas.

相容性

注意

由於排程器的差異，在本地執行的作業在使用不同的排程器時可能無法運作，原因是網路或軟體相依性。

特性	排程器支援
擷取日誌	✔️
分散式作業	LocalScheduler 支援多個副本，但所有副本都將在本地主機上執行。
取消作業	✔️
描述作業	✔️
工作區 / 修補	部分支援。LocalScheduler 從本地目錄執行應用程式，但不支援程式化工作區。
掛載	❌
彈性	❌

auto_set_CUDA_VISIBLE_DEVICES(role_params: Dict[str, List[ReplicaParam]], app: AppDef, cfg: LocalOpts) → None

如果執行選項 auto_set_cuda_visible_devices = True，則根據每個角色的資源規格中指定的 GPU 數量，將 CUDA_VISIBLE_DEVICES 環境變數設定為每個副本的（節點）環境變數，覆寫角色的 env 欄位中任何現有的 CUDA_VISIBLE_DEVICES。若要手動設定 CUDA_VISIBLE_DEVICES，請在排程器 runcfg 中使用 auto_set_cuda_visible_devices = False 執行。

注意

如果主機的裝置數量少於請求的 GPU 總數，則 CUDA_VISIBLE_DEVICES 不會被設定（即使 auto_set_cuda_visible_devices=True）。

注意

此方法會在所有 GPU 角色上設定 CUDA_VISIBLE_DEVICES，或者完全不設定

範例（所有範例都假設在具有 8 個 GPU 的主機上執行）

1. Role(num_replicas=2, resource=Resource(gpus=2))

   1. replica_0 的 CUDA_VISIBLE_DEVICES=0,1

   2. replica_1 的 CUDA_VISIBLE_DEVICES=2,3

2. Role(num_replicas=3, resource=Resource(gpus=4))

   1. 錯誤 - `` 3 * 4 = 12 >= 8``

3. [Role(num_replicas=1, resource=Resource(gpus=2)), Role(num_replicas=3, resource=Resource(gpus=1))]

   1. role_0, replica_0 的 CUDA_VISIBLE_DEVICES=0,1

   2. role_1、replica_0 的 CUDA_VISIBLE_DEVICES=2

   3. role_1、replica_1 的 CUDA_VISIBLE_DEVICES=3

   4. role_1、replica_2 的 CUDA_VISIBLE_DEVICES=4

close() → None

僅適用於具有本地狀態的排程器！關閉排程器並釋放任何已分配的資源。關閉後，排程器物件將被視為無效，並且對物件呼叫的任何方法都會導致未定義的行為。

這個方法不應引發例外，並且允許在同一個物件上多次呼叫。

注意

僅針對具有本地狀態的排程器實作進行覆寫 (torchx/schedulers/local_scheduler.py)。僅封裝遠端排程器客戶端的排程器不需要實作這個方法。

describe(app_id: str) → Optional[DescribeAppResponse]

描述指定的應用程式。

回傳值：

AppDef 描述，如果應用程式不存在，則為 None。

list() → List[ListAppResponse]

對於在排程器上啟動的應用程式，此 API 會回傳 ListAppResponse 物件清單，每個物件都包含應用程式 ID 及其狀態。注意：此 API 處於原型階段，可能會有所變更。

log_iter(app_id: str, role_name: str, k: int = 0, regex: Optional[str] = None, since: Optional[datetime] = None, until: Optional[datetime] = None, should_tail: bool = False, streams: Optional[Stream] = None) → Iterable[str]

回傳一個迭代器，指向 k``th 副本 的 ``role 的日誌行。當所有符合條件的日誌行都被讀取後，迭代器就會結束。

如果排程器支援基於時間的游標來擷取自訂時間範圍內的日誌行，則會採用 since、until 欄位，否則將會忽略它們。未指定 since 和 until 等同於取得所有可用的日誌行。如果 until 為空，則迭代器的行為類似於 tail -f，會持續追蹤日誌輸出，直到作業達到終止狀態為止。

日誌的確切定義因排程器而異。有些排程器可能會將 stderr 或 stdout 視為日誌，而其他排程器可能會從日誌檔案中讀取日誌。

行為和假設

1. 如果在不存在的應用程式上呼叫，則會產生未定義的行為。呼叫者應在呼叫此方法之前，使用 exists(app_id) 檢查應用程式是否存在。

2. 不是有狀態的，使用相同參數呼叫此方法兩次會回傳新的迭代器。先前的迭代進度將會遺失。

3. 不保證一定支援日誌追蹤。並非所有排程器都支援即時日誌迭代（例如，在應用程式執行時追蹤日誌）。如需迭代器行為的詳細資訊，請參閱特定排程器的說明文件。

3.1 如果排程器支援日誌追蹤，則應由

should_tail 參數控制。

4. 不保證日誌保留。到呼叫此方法時，基礎排程器可能已清除此應用程式的日誌記錄。如果是這樣，此方法會引發任意例外狀況。

5. 如果 should_tail 為 True，則只有在可存取的日誌行已完全耗盡且應用程式已達到最終狀態時，方法才會引發 StopIteration 例外狀況。例如，如果應用程式卡住且未產生任何日誌行，則迭代器會封鎖，直到應用程式最終被終止（透過逾時或手動方式），此時它會引發 StopIteration。

   如果 should_tail 為 False，則方法在沒有更多日誌時引發 StopIteration。

6. 並非所有排程器都需要支援。

7. 有些排程器可能會透過支援 __getitem__ 來支援行游標（例如，iter[50] 會搜尋到第 50 個日誌行）。

8. 空格會被保留，每個新行都應包含 \n。若要

   支援互動式進度條，回傳的行不需要包含 \n，但應在沒有換行的情況下列印，才能正確處理 \r 歸位字元。

參數：

streams – 要選擇的 IO 輸出串流。選項包括：combined、stdout、stderr。如果排程器不支援所選的串流，它會擲回 ValueError。

回傳值：

指定角色副本的日誌行的 Iterator

引發：

NotImplementedError – 如果排程器不支援日誌迭代

schedule(dryrun_info: AppDryRunInfo[PopenRequest]) → str

與 submit 相同，但它採用 AppDryRunInfo。建議實作者實作此方法，而不是直接實作 submit，因為 submit 可以透過以下方式輕鬆實作

dryrun_info = self.submit_dryrun(app, cfg)
return schedule(dryrun_info)

映像提供者

class torchx.schedulers.local_scheduler.ImageProvider

管理在本地主機上下載和設定映像。這僅適用於 LocalhostScheduler，因為通常真正的排程器會代表使用者執行此操作。

abstract fetch(image: str) → str

提取給定的映像，並傳回本地主機上提取映像的路徑，如果沒有操作則傳回空字串

fetch_role(role: Role) → str

與 fetch(image) 相同，它會提取角色的映像並傳回映像根目錄的路徑，不同之處在於它允許此提供者更新角色。當需要在角色上設定額外的環境變數以符合映像提供者在本地主機上提取和管理映像的方式時，這非常有用。根據預設，此方法僅委派給 fetch(role.image)。如有必要，請覆寫。

get_cwd(image: str) → Optional[str]

傳回已掛載 img 目錄的絕對路徑。用作啟動子進程的工作目錄。

get_entrypoint(img_root: str, role: Role) → str

傳回進入點的位置。

get_replica_param(img_root: str, role: Role, stdout: Optional[str] = None, stderr: Optional[str] = None, combined: Optional[str] = None) → ReplicaParam

給定角色副本的規格，傳回 ReplicaParam 持有者，其中包含最終傳遞給 subprocess.Popen 的參數，以實際調用和運行每個角色的副本。預計 img_root 是 self.fetch(role.image) 的傳回值。由於角色的映像只需提取一次（而不是每個副本都提取），因此預計調用者為每個角色調用一次 fetch 方法，並為每個 role.num_replicas 調用此方法。

class torchx.schedulers.local_scheduler.CWDImageProvider(cfg: LocalOpts)

與 LocalDirectoryImageProvider 類似，但它會忽略映像名稱，並使用目前的工作目錄作為映像路徑。

範例

1. fetch(Image(name="/tmp/foobar")) 傳回 os.getcwd()

2. fetch(Image(name="foobar:latest")) 傳回 os.getcwd()

fetch(image: str) → str

提取給定的映像，並傳回本地主機上提取映像的路徑，如果沒有操作則傳回空字串

get_cwd(image: str) → Optional[str]

傳回已掛載 img 目錄的絕對路徑。用作啟動子進程的工作目錄。

get_entrypoint(img_root: str, role: Role) → str

傳回進入點的位置。

class torchx.schedulers.local_scheduler.LocalDirectoryImageProvider(cfg: LocalOpts)

將映像名稱解釋為本地主機上目錄的路徑。不會“提取”（例如下載）任何內容。與 LocalScheduler 結合使用以運行本地二進制檔案。

映像名稱必須是絕對路徑，並且必須存在。

範例

1. fetch(Image(name="/tmp/foobar")) 傳回 /tmp/foobar

2. fetch(Image(name="foobar")) 引發 ValueError

3. fetch(Image(name="/tmp/dir/that/does/not_exist")) 引發 ValueError

fetch(image: str) → str

引發：

ValueError – 如果映像檔名稱不是絕對路徑，或者如果它不存在或不是目錄

get_cwd(image: str) → Optional[str]

傳回絕對工作目錄。用作子程序的工作目錄。

get_entrypoint(img_root: str, role: Role) → str

傳回角色進入點。當使用 image_type=dir 執行本地排程器時，子程序工作目錄將被設定為 img_root。如果 role.entrypoint 是相對路徑，則它將被解析為 img_root/role.entrypoint，如果 role.entrypoint 是絕對路徑，則將按原樣執行。

參考

torchx.schedulers.local_scheduler.create_scheduler(session_name: str, cache_size: int = 100, extra_paths: ~typing.Optional[~typing.List[str]] = None, image_provider_class: ~typing.Callable[[~torchx.schedulers.local_scheduler.LocalOpts], ~torchx.schedulers.local_scheduler.ImageProvider] = <class 'torchx.schedulers.local_scheduler.CWDImageProvider'>, **kwargs: ~typing.Any) → LocalScheduler

class torchx.schedulers.local_scheduler.LogIterator(app_id: str, log_file: str, scheduler: Scheduler, should_tail: bool = True)

class torchx.schedulers.local_scheduler.PopenRequest(app_id: str, log_dir: str, role_params: Dict[str, List[ReplicaParam]], role_log_dirs: Dict[str, List[str]])

保存用於為應用程序中每個角色的每個副本創建子程序的參數。

class torchx.schedulers.local_scheduler.ReplicaParam(args: List[str], env: Dict[str, str], stdout: Optional[str] = None, stderr: Optional[str] = None, combined: Optional[str] = None, cwd: Optional[str] = None)

保存每個角色副本的 LocalScheduler._popen() 參數。

class torchx.schedulers.local_scheduler.SignalException(msg: str, sigval: Signals)

當 torchx 本地排程器程序收到終止信號時，運行時會引發異常。