Executar o Python colocalizado com o Pathways

Para evitar o roteamento de trabalho vinculado ao host, como carregamento de dados e checkpoint, por meio de um único controlador do Pathways no Google Kubernetes Engine (GKE), execute essas funções nas VMs de worker do Cloud TPU usando a API Python colocalizada do JAX.

Este documento, destinado a engenheiros de machine learning, descreve como o Python colocalizado funciona com o Pathways. Você vai aprender a criar, implantar e verificar um contêiner secundário com um manifesto JobSet ou o Cluster Toolkit.

Antes de começar

Siga os seguintes pré-requisitos:

Funções exigidas

Conceda os seguintes papéis do Identity and Access Management (IAM):

  • Sua conta de usuário:
    • Gravador do Artifact Registry (roles/artifactregistry.writer) no projeto do Google Cloud para enviar imagens de arquivo secundário personalizadas para o Artifact Registry.
    • Desenvolvedor do Kubernetes Engine (roles/container.developer) no projeto do Google Cloud para implantar recursos do JobSet, encaminhar portas e ler registros de pods no GKE.
  • Conta de serviço do pool de nós do GKE: os pods do Pathways usam essa conta de serviço quando os pools de nós usam a flag --workload-metadata=GCE_METADATA, conforme configurado em Criar um cluster do GKE com o Pathways:
    • Leitor do Artifact Registry (roles/artifactregistry.reader) no projeto do Google Cloud que hospeda seu repositório particular para extrair imagens de arquivo secundário personalizadas.
    • Administrador de objetos do Storage (roles/storage.objectAdmin) no bucket temporário do Cloud Storage para o cache de compilação e outros arquivos temporários.

Opcional: para permitir que o contêiner do gerenciador de recursos do Pathways (pathways-rm) adicione uma regra de ciclo de vida do bucket que expira entradas antigas do cache de compilação, conceda também o papel de Administrador do Storage (roles/storage.admin) no bucket de rascunho. Sem esse papel, o contêiner pathways-rm registra um aviso e continua usando o cache. Para pular a atualização do ciclo de vida, transmita a flag --enable_gcs_olm=false para o contêiner pathways-rm.

Se os pools de nós usarem a Federação de Identidade da Carga de Trabalho para GKE, conceda o papel de bucket temporário à conta de serviço do Kubernetes usada pelos pods do Pathways ou à conta de serviço do IAM vinculada. Por padrão, os pods do Pathways usam a conta de serviço default, a menos que o manifesto JobSet defina o campo serviceAccountName. Mantenha o papel de Leitor do Artifact Registry na conta de serviço do pool de nós.

Como o Python colocalizado funciona com o Pathways

No Pathways, o script do controlador JAX é executado em um único host de CPU, enquanto os pods de worker do Cloud TPU executam o contêiner C++ pathways-worker. Para executar funções @colocated_python e métodos @colocated_python_class em hosts de worker, o Python colocalizado usa os seguintes componentes:

  • Seu controlador JAX: usa o módulo jax.experimental.colocated_python para parear cada chip do Cloud TPU com um dispositivo de CPU host e serializar sua função do Python e metadados de tipo com a biblioteca cloudpickle.
  • O contêiner pathways-proxy (no pod pathways-head): recebe a função serializada por gRPC e a encaminha para o contêiner pathways-worker nas VMs de worker que possuem os dispositivos de CPU de entrada da chamada. Transmitir a flag --sidecar_name=external configura o contêiner pathways-proxy para segmentar o contêiner colocated-python-sidecar.
  • O contêiner pathways-worker (em cada pod de worker): carrega a função serializada no contêiner secundário local, aciona a execução no gRPC local e troca buffers de matriz por um volume emptyDir compartilhado na memória (medium: Memory).
  • O contêiner colocated-python-sidecar (em cada pod de worker): descompacta e executa a função em um ambiente de execução isolado do Python 3.12 uma vez por VM nos fragmentos locais dessa VM, gravando matrizes de saída diretamente na memória do host compartilhada.

Para saber mais sobre a arquitetura do Pathways, consulte Componentes do Pathways.

Fluxo de execução

Quando você invoca uma função decorada, o Pathways a executa no cluster em duas etapas:

  1. Roteamento de funções: o módulo jax.experimental.colocated_python empacota a função em um programa Interim Framework Runtime (IFRT) e a envia para o contêiner pathways-proxy. O proxy encaminha o programa apenas para as VMs de worker que contêm os fragmentos de entrada, sendo executado uma vez por VM em todos os fragmentos locais.
  2. Execução de memória compartilhada: o contêiner pathways-worker grava fragmentos de entrada no volume compartilhado na memória (/tmp/sidecar ou /tmp/shared-memory) e invoca o contêiner colocated-python-sidecar por TCP de loopback (localhost:50051) ou um soquete de domínio Unix (/sock/sidecar.sock). As matrizes de saída retornam pela memória compartilhada sem cópias do gRPC e são movidas diretamente para a memória de alta largura de banda (HBM) do Cloud TPU quando colocadas em dispositivos do Cloud TPU.

Para saber como usar a API JAX, como descobrir dispositivos de CPU colocalizados e declarar especificações de saída para envio assíncrono, consulte o guia do Python colocalizado do JAX.

Diretrizes de design

Ao escrever funções Python colocalizadas, siga estas diretrizes:

  • Minimize as variáveis capturadas: transmita dados de matriz como argumentos jax.Array fragmentados em vez de capturar matrizes grandes ou objetos não serializáveis (como arquivos abertos ou clientes de rede) em closures. Abra arquivos ou clientes dentro de uma instância @colocated_python_class no worker.
  • Recriar o estado @colocated_python_class após reinicializações: os objetos sidecar com estado persistem nas etapas na memória, mas não são salvos automaticamente se um pod de worker for reiniciado ou se as contagens de frações mudarem durante o treinamento elástico. Recrie objetos com estado de um checkpoint após o redimensionamento ou as reinicializações.

Imagens e tags predefinidas

OGoogle Cloud publica imagens pré-criadas do Pathways em um repositório público do Artifact Registry:

  • Sidecar do Python colocalizado: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/colocated_python_sidecar:TAG
  • Gerenciador de recursos e worker do Pathways: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/server:TAG
  • Servidor proxy IFRT: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/proxy_server:TAG

Use tags correspondentes nas imagens server, proxy_server e colocated_python_sidecar.

As imagens de arquivo secundário pré-criadas são compatíveis com as versões 0.10.1, 0.10.2, 0.11.0, 0.11.1, 0.11.2, 0.12.0 e 0.12.0.1 do JAX. Substitua TAG por um dos seguintes formatos de tag:

  • jax-JAX_VERSION (recomendado): uma tag contínua para uma versão específica do JAX, como jax-0.12.0.1.
  • YYYYMMDD-jax_JAX_VERSION: uma tag de build com carimbo de data/hora, como 20261110-jax_0.12.0.1.

Se você precisar de uma versão de imagem exata que nunca mude, fixe a imagem pelo resumo SHA-256. Para procurar um resumo de imagem, use o comando gcloud artifacts docker images describe:

IMAGE_REPO="us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways"
gcloud artifacts docker images describe \
    "${IMAGE_REPO}/colocated_python_sidecar:jax-JAX_VERSION" \
    --format="value(image_summary.digest)"

Substitua JAX_VERSION pela sua versão do JAX, como 0.12.0.1.

Criar uma imagem de arquivo secundário personalizada

A imagem de arquivo secundário pré-criada inclui os pacotes jax, jaxlib, numpy, scipy, ml-dtypes, opt-einsum, cloudpickle e absl-py. Se as funções do Python colocalizadas usarem apenas esses pacotes, pule para Implantar um JobSet do Pathways com o arquivo secundário ou Implantar com o Cluster Toolkit.

Para adicionar dependências personalizadas do Python, coloque-as em camadas na imagem pré-criada que corresponde à sua versão do JAX:

  1. Em um diretório de build vazio, crie um arquivo requirements.txt para seus pacotes extras. Omita os pacotes jax e jaxlib, que já estão instalados e fixados no arquivo /opt/venv/server_constraints.txt:

    grain
    
  2. Crie um Dockerfile que instale os pacotes no arquivo requirements.txt, limitado pelo arquivo /opt/venv/server_constraints.txt:

    ARG JAX_VERSION=0.12.0.1
    ARG IMAGE_REPO=us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways
    FROM ${IMAGE_REPO}/colocated_python_sidecar:jax-${JAX_VERSION}
    
    WORKDIR /app
    COPY requirements.txt .
    
    RUN uv pip install -r requirements.txt \
            -c /opt/venv/server_constraints.txt && \
        uv cache clean
    

    Mantenha as instruções ENTRYPOINT e CMD da imagem de base inalteradas. Se o arquivo requirements.txt instalar pacotes de URLs do Git, adicione a seguinte instrução RUN antes da instrução uv pip install RUN, porque a imagem de base slim omite a ferramenta git:

    RUN apt-get update && \
        apt-get install -y --no-install-recommends git && \
        rm -rf /var/lib/apt/lists/*
    
  3. Autentique o Docker na região do Artifact Registry usando o comando gcloud auth configure-docker:

    gcloud auth configure-docker REGISTRY_LOCATION-docker.pkg.dev
    

    Substitua REGISTRY_LOCATION pelo local do Artifact Registry, como us ou us-central1.

  4. Crie e envie sua imagem de arquivo secundário personalizada:

    export JAX_VERSION=JAX_VERSION
    IMAGE_PREFIX=REGISTRY_LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY
    export SIDECAR_IMAGE="${IMAGE_PREFIX}/colocated-sidecar:jax-${JAX_VERSION}"
    
    docker build --build-arg JAX_VERSION="${JAX_VERSION}" \
        --tag "${SIDECAR_IMAGE}" .
    docker push "${SIDECAR_IMAGE}"
    

    Substitua:

    • JAX_VERSION: sua versão do JAX, como 0.12.0.1.
    • REGISTRY_LOCATION: o local do Artifact Registry, como us ou us-central1.
    • PROJECT_ID: o ID do projeto doGoogle Cloud .
    • REPOSITORY: o nome do repositório do Docker do Artifact Registry.

Implantar um JobSet do Pathways com o arquivo secundário

É possível implantar o Pathways com o arquivo secundário aplicando um manifesto JobSet com a ferramenta de linha de comando kubectl nesta seção ou enviando o job diretamente com a CLI gcluster em Implantar com o Cluster Toolkit.

Para gerar e aplicar um manifesto JobSet, siga estas etapas:

  1. Gere um manifesto JobSet (pathways-colocated-jobset.yaml) com uma das seguintes ferramentas:

    • O builder Python pathways-utils: configure um JobSet com o builder PathwaysJobSet chamando os métodos .add_colocated_python("SIDECAR_IMAGE") e .export_yaml("pathways-colocated-jobset.yaml"). Se você usar o pacote pathwaysutils (versão 0.1.14 ou anterior do PyPI), também transmita o argumento proxy_container_kwargs={"args": ["--sidecar_name=external"]} para o construtor PathwaysJobSet ou instale o pacote pathways-utils da ramificação main.
    • Cluster Toolkit (gcluster): execute o comando gcluster job submit com a flag --pathways-colocated-python-sidecar-image e anexe a flag --dry-run-out=pathways-colocated-jobset.yaml para renderizar o manifesto localmente sem enviar o job.

    Substitua SIDECAR_IMAGE pelo URI da imagem de arquivo secundário personalizada ou pelo URI da imagem pré-criada colocated_python_sidecar.

    Os dois geradores configuram o manifesto para fazer o seguinte:

    • Execute o contêiner colocated-python-sidecar no campo initContainers com restartPolicy: Always em cada pod de worker. A CLI gcluster nomeia o job replicado do worker como worker, enquanto o builder PathwaysJobSet o nomeia como pathways-worker.
    • Transmita a flag --sidecar_name=external para o contêiner pathways-proxy e conecte o contêiner pathways-worker ao arquivo secundário por TCP de loopback em localhost:50051. Quando o contêiner pathways-proxy é executado no campo initContainers, ele também usa restartPolicy: Always.
    • Monte um volume emptyDir na memória com medium: Memory nos dois contêineres de pod de worker: em /tmp/sidecar nos manifestos gcluster ou em /tmp/shared-memory nos manifestos PathwaysJobSet. Os dois geradores também definem a variável de ambiente CLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORY no arquivo secundário e a flag --cloud_pathways_sidecar_shm_directory no contêiner pathways-worker.
  2. Aplique o manifesto JobSet e aguarde até que os pods alcancem o status Running:

    kubectl apply -f pathways-colocated-jobset.yaml
    kubectl get pods -l jobset.sigs.k8s.io/jobset-name=JOBSET_NAME
    

    Substitua JOBSET_NAME pelo valor metadata.name do JobSet.

Execute uma sessão de cliente JAX por implantação de JobSet. Depois que um cliente se desconecta, um contêiner pathways-worker reiniciado não pode reutilizar um arquivo secundário em execução. Exclua e recrie o JobSet antes de iniciar outra sessão.

Os arquivos em um volume emptyDir na memória são contabilizados no uso da memória do pod. Defina o campo emptyDir.sizeLimit (como 175Gi) no volume de memória compartilhada para limitar o uso por nó. Por padrão, os dois contêineres retêm a memória compartilhada liberada por 30 segundos de inatividade para reutilização. Para mudar essa janela, defina a flag --pathways_sidecar_shared_memory_idle_release_secs=SECONDS no campo args do contêiner colocated-python-sidecar (ao lado da flag --port=50051 ou --unix_domain_socket_path) e a flag --cloud_pathways_shared_memory_idle_release_secs=SECONDS no campo args do contêiner pathways-worker. Substitua SECONDS pelo tempo limite de inatividade em segundos. Definir as duas flags como 0 libera as páginas em cerca de 1 segundo, o que reduz o uso da memória ao custo de uma sobrecarga de alocação extra.

Opcional: usar um soquete de domínio Unix

Para usar um soquete de domínio Unix (UDS) em /sock/sidecar.sock em vez de abrir uma porta TCP em pods de worker que definem hostNetwork: true, aplique as seguintes substituições ao manifesto JobSet antes de executar o comando kubectl apply:

  • Monte um volume emptyDir: {} chamado sidecar-socket em /sock nos contêineres pathways-worker e colocated-python-sidecar.
  • Defina args: ["--unix_domain_socket_path=/sock/sidecar.sock"] e um exec startupProbe (test -S /sock/sidecar.sock) no contêiner colocated-python-sidecar.
  • Anexe a flag --cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sock ao campo args do contêiner pathways-proxy.

Implantar com o Cluster Toolkit

No Cluster Toolkit (gcluster versão 1.108.0 ou mais recente), transmitir a flag --pathways-colocated-python-sidecar-image para o comando gcluster job submit configura o contêiner colocated-python-sidecar por TCP de loopback (localhost:50051), monta o volume na memória em /tmp/sidecar e define a flag --sidecar_name=external. Transmita as flags --pathways-server-image e --pathways-proxy-server-image explicitamente para que as três imagens usem tags cloud-pathways correspondentes.

Envie uma implantação do Pathways sem interface gráfica com sua imagem de arquivo secundário para executar scripts de cliente interativos nela:

IMAGE_REPO="us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways"

gcluster job submit \
    --pathways \
    --pathways-headless \
    --pathways-gcs-location="gs://BUCKET_NAME/pathways-artifacts" \
    --pathways-server-image="${IMAGE_REPO}/server:jax-JAX_VERSION" \
    --pathways-proxy-server-image="${IMAGE_REPO}/proxy_server:jax-JAX_VERSION" \
    --pathways-colocated-python-sidecar-image="SIDECAR_IMAGE" \
    --name=WORKLOAD \
    --cluster=CLUSTER \
    --project=PROJECT_ID \
    --location=LOCATION \
    --num-slices=WORKLOAD_NODEPOOL_COUNT \
    --compute-type=COMPUTE_TYPE \
    --topology=TOPOLOGY

Substitua:

  • BUCKET_NAME: seu bucket de rascunho do Cloud Storage.
  • JAX_VERSION: sua versão do JAX, como 0.12.0.1.
  • SIDECAR_IMAGE: o URI da imagem de arquivo secundário personalizada ou pré-criada.
  • WORKLOAD: um nome exclusivo de JobSet (22 caracteres ou menos).
  • CLUSTER: o nome do cluster do GKE.
  • PROJECT_ID: o ID do projeto doGoogle Cloud .
  • LOCATION: a região ou zona do cluster do GKE.
  • WORKLOAD_NODEPOOL_COUNT: o número de frações do Cloud TPU, como 1.
  • COMPUTE_TYPE: o tipo de máquina do Cloud TPU, como ct5lp-hightpu-4t ou ct6e-standard-4t.
  • TOPOLOGY: a topologia da fração da Cloud TPU, como 4x8 ou 2x4.

Também é possível personalizar como o comando gcluster job submit executa ou exporta o job:

  • Cargas de trabalho em lote: para executar um job em lote conteinerizado dentro do pod pathways-head em vez de uma implantação headless, substitua a flag --pathways-headless pelas flags --image="CLIENT_IMAGE" e --command="COMMAND". Use uma imagem de cliente JAX do Python 3.12 criada com pins server_constraints.txt e transmita o comando de entrada (como python colocated_example.py).
  • Renderização de manifesto local: anexe a flag --dry-run-out=pathways-colocated-jobset.yaml para renderizar o manifesto JobSet localmente sem enviá-lo.
  • Sessões headless subsequentes: execute o comando gcluster job cancel e reenvie o job antes de iniciar outra sessão do cliente.

Executar uma carga de trabalho do Python colocalizada

Execute o script do cliente JAX com a variável de ambiente JAX_PLATFORMS=proxy no contêiner pathways-proxy, seja no contêiner de carga de trabalho pathways-head ou por encaminhamento de portas:

  1. Para alinhar as dependências de serialização com a imagem do arquivo secundário, extraia o arquivo /opt/venv/server_constraints.txt e instale os pacotes correspondentes em um ambiente virtual do Python 3.12:

    IMAGE_REPO="us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways"
    docker run --rm --entrypoint cat \
        "${IMAGE_REPO}/colocated_python_sidecar:jax-JAX_VERSION" \
        /opt/venv/server_constraints.txt > constraints.txt
    python3.12 -m venv .venv
    source .venv/bin/activate
    python -m pip install -c constraints.txt \
        jax jaxlib cloudpickle pathwaysutils
    

    Substitua JAX_VERSION pela versão do JAX, como 0.12.0.1.

  2. Se você executar o cliente fora do pod pathways-head, encaminhe a porta local 29000 para o contêiner pathways-proxy em um terminal separado:

    JOBSET_LABEL="jobset.sigs.k8s.io/jobset-name=JOBSET_NAME"
    ROLE_LABEL="jobset.sigs.k8s.io/replicatedjob-name=pathways-head"
    HEAD_POD=$(kubectl get pods -l "${JOBSET_LABEL},${ROLE_LABEL}" \
        -o jsonpath='{.items[0].metadata.name}')
    kubectl port-forward "${HEAD_POD}" 29000:29000
    

    Substitua JOBSET_NAME pelo valor metadata.name do JobSet (ou o nome WORKLOAD que você transmitiu ao comando gcluster job submit).

  3. Salve o script a seguir como colocated_example.py. Esse script aloca uma matriz NumPy de 4 MiB na memória do host compartilhada no dispositivo de CPU colocalizado de cada worker do Cloud TPU e a transfere para a HBM do Cloud TPU:

    import jax
    from jax.experimental import colocated_python
    import numpy as np
    import pathwaysutils
    
    pathwaysutils.initialize()
    
    @colocated_python.colocated_python
    def make_host_array(seed_arr: jax.Array) -> jax.Array:
      host_array = np.full(
          (1024, 1024), fill_value=float(seed_arr), dtype=np.float32
      )
      return jax.device_put(host_array, seed_arr.device)
    
    tpu_devices = jax.devices()
    cpu_devices = colocated_python.colocated_cpu_devices(tpu_devices)
    print(
        f"TPU devices: {len(tpu_devices)}, "
        f"colocated CPU devices: {len(cpu_devices)}"
    )
    
    host_arrays = [
        make_host_array(jax.device_put(np.int32(i + 1), cpu_dev))
        for i, cpu_dev in enumerate(cpu_devices)
    ]
    tpu_arrays = [
        jax.device_put(host_arr, tpu_dev)
        for host_arr, tpu_dev in zip(host_arrays, tpu_devices)
    ]
    for arr in tpu_arrays:
      arr.block_until_ready()
    
    print(
        f"Transferred {len(tpu_arrays)} arrays of shape {tpu_arrays[0].shape} "
        f"to TPU HBM; sample sum={float(tpu_arrays[0].sum()):.1f}"
    )
    
  4. Execute o script no servidor proxy do IFRT:

    JAX_PLATFORMS=proxy JAX_BACKEND_TARGET=grpc://127.0.0.1:29000 \
        python colocated_example.py
    

    O resultado será o seguinte:

    TPU devices: 8, colocated CPU devices: 8
    Transferred 8 arrays of shape (1024, 1024) to TPU HBM; sample sum=1048576.0
    

    Em cargas de trabalho de produção de várias frações, transmita um argumento jax.Array fragmentado colocado nos dispositivos retornados pela chamada colocated_python.colocated_cpu_devices(mesh) e defina o parâmetro out_specs_fn com o método .specialize(out_specs_fn=...) para que o Pathways execute uma chamada paralela em todos os sidecars de worker sem esperar.

    Não execute scripts de cliente em um pod worker com a variável de ambiente JAX_PLATFORMS=cpu, porque essa configuração executa o JAX localmente em uma CPU e ignora o Pathways. Ignore qualquer mensagem IFRT proxy server disconnected: CANCELLED exibida ao sair.

Para mais padrões de uso, consulte os seguintes recursos:

Verificar a implantação do arquivo secundário

Execute o comando kubectl logs em um JobSet sem comando antes de cancelá-lo ou excluí-lo ou enquanto uma carga de trabalho em lote ainda estiver em execução. Nas implantações em lote de JobSet, o controlador JobSet exclui os pods worker assim que o job pathways-head é concluído. Em vez disso, confira os registros de lote concluídos no Cloud Logging, conforme descrito em Resolver problemas do Pathways no Cloud.

Para verificar uma implantação em execução com a ferramenta de linha de comando kubectl, siga estas etapas:

  1. Inspecione os registros do contêiner colocated-python-sidecar:

    JOBSET_LABEL="jobset.sigs.k8s.io/jobset-name=JOBSET_NAME"
    ROLE_LABEL="jobset.sigs.k8s.io/replicatedjob-name=worker"
    WORKER_POD=$(kubectl get pods -l "${JOBSET_LABEL},${ROLE_LABEL}" \
        -o jsonpath='{.items[0].metadata.name}')
    kubectl logs "${WORKER_POD}" -c colocated-python-sidecar
    

    Substitua JOBSET_NAME pelo valor metadata.name do JobSet (ou o nome WORKLOAD que você transmitiu ao comando gcluster job submit). Se você gerou o manifesto com o builder PathwaysJobSet, defina replicatedjob-name=pathways-worker na variável ROLE_LABEL.

    O resultado será o seguinte:

    Started SidecarGrpcServer on localhost:50051
    ...
    SidecarServer agreed on protocol version: 6
    Installed shared memory allocator for colocated Python using file /tmp/sidecar/pathways_shm_sidecar
    

    Confirme se a saída mostra a mensagem de inicialização do gRPC e, após a primeira chamada @colocated_python, a mensagem do alocador de memória compartilhada. Os manifestos gerados com o builder PathwaysJobSet usam o diretório /tmp/shared-memory, e as implantações do UDS registram unix:/sock/sidecar.sock em vez de localhost:50051.

  2. Inspecione os registros do contêiner pathways-worker no mesmo pod:

    kubectl logs "${WORKER_POD}" -c pathways-worker \
        | grep -iE "shared memory|external sidecar"
    

    O resultado será o seguinte:

    Enabled shared memory for external sidecar in /tmp/sidecar
    External sidecar connected to backing GRPC sidecar at localhost:50051
    

    Confirme se o contêiner pathways-worker ativou a memória compartilhada e se conectou ao arquivo secundário.

Ao executar o comando kubectl exec para inspecionar o diretório de memória compartilhada, direcione o contêiner colocated-python-sidecar com a flag -c colocated-python-sidecar, porque o contêiner pathways-worker não inclui um shell.

Resolver problemas do Python colocalizado

As seções a seguir descrevem como resolver problemas comuns do Python colocalizado.

Unable to unpickle erro

Se a carga de trabalho falhar com o erro a seguir, as versões do Python ou do pacote serão diferentes entre o cliente JAX e o contêiner secundário:

jax.errors.JaxRuntimeError: UNKNOWN: Unable to unpickle the callable and specialization

Verifique se o cliente executa o Python 3.12 (python --version) e instale os pacotes do cliente com a flag -c constraints.txt extraída da imagem do arquivo secundário. Para mais informações, consulte Executar uma carga de trabalho do Python colocalizada.

Conflito de dependência durante uma execução de docker build

Se o comando uv pip install falhar com o erro No solution found when resolving dependencies, um fixo no arquivo requirements.txt está em conflito com o arquivo /opt/venv/server_constraints.txt. Remova os pacotes jax e jaxlib do arquivo requirements.txt e flexibilize os pins de versão em pacotes como numpy, ml-dtypes ou scipy.

Erro de arquivo secundário não ativado

Se o contêiner pathways-proxy for encerrado com o erro Sidecar create args were set, but sidecar was not enabled, adicione a flag --sidecar_name=external ao campo args do contêiner pathways-proxy.

Sidecar already initialized erro

Se a carga de trabalho falhar com o erro FAILED_PRECONDITION: Sidecar already initialized, uma desconexão anterior do cliente reiniciou o contêiner pathways-worker enquanto o contêiner colocated-python-sidecar permaneceu inicializado. Exclua e recrie o JobSet antes de iniciar outra sessão do cliente.

Erros de memória compartilhada ou de conexão do arquivo secundário

Use as seguintes verificações para resolver erros de montagem de memória compartilhada, conexão gRPC ou memória do host:

  • Failed to stat sidecar_shm_directory: monte o volume de memória compartilhada emptyDir no caminho correspondente (/tmp/sidecar ou /tmp/shared-memory) nos contêineres pathways-worker e colocated-python-sidecar.
  • Timed out connecting to sidecar gRPC service ou Failed to connect to external sidecar: confirme se o contêiner colocated-python-sidecar é executado no campo initContainers com restartPolicy: Always e se as três imagens cloud-pathways usam tags correspondentes. Verifique se as configurações de TCP (--port=50051) ou UDS (volume /sock e --unix_domain_socket_path=/sock/sidecar.sock) correspondem entre os contêineres pathways-proxy e colocated-python-sidecar.
  • Host do worker sem memória após grandes bursts de matriz: defina a flag --pathways_sidecar_shared_memory_idle_release_secs=0 no contêiner colocated-python-sidecar (ao lado da flag --port=50051 ou --unix_domain_socket_path) e a flag --cloud_pathways_shared_memory_idle_release_secs=0 no contêiner pathways-worker. Definir as duas sinalizações como 0 libera a memória compartilhada não utilizada em cerca de 1 segundo. Como alternativa, reduza a quantidade máxima de dados de matriz de host que a carga de trabalho mantém na memória de uma só vez.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste documento, exclua a implantação e os artefatos temporários quando terminar:

  • Manifesto JobSet: exclua o recurso JobSet:

    kubectl delete jobset JOBSET_NAME
    

    Substitua JOBSET_NAME pelo valor metadata.name do JobSet.

  • Cluster Toolkit: cancele o job implantado:

    gcluster job cancel WORKLOAD \
        --cluster=CLUSTER \
        --project=PROJECT_ID \
        --location=LOCATION
    

    Substitua:

    • WORKLOAD: o nome do job do Pathways.
    • CLUSTER: o nome do cluster do GKE.
    • PROJECT_ID: o ID do projeto doGoogle Cloud .
    • LOCATION: a região ou zona do cluster do GKE.

Opcional: exclua as imagens de arquivo secundário personalizadas no Artifact Registry e remova os objetos temporários no bucket de rascunho do Cloud Storage. Quando você não precisar mais do cluster do GKE, exclua-o seguindo as etapas de limpeza em Criar um cluster do GKE com o Pathways.

A seguir