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:
- Crie um cluster do GKE com o Pathways.
- Instale a ferramenta de linha de comando
kubectle o plug-ingke-gcloud-auth-plugin. - Instale a CLI do Google Cloud.
- Instale o Docker.
- Ative a API Kubernetes Engine e a API Artifact Registry.
- Crie um bucket de rascunho do Cloud Storage para arquivos temporários do Pathways.
- Se você planeja criar uma imagem de arquivo secundário personalizada, crie um repositório do Docker do Artifact Registry.
- Instale o Python 3.12 no ambiente do cliente que executa a carga de trabalho do JAX.
- Opcional: para implantar com o
Cluster Toolkit,
instale a versão 1.108.0 ou mais recente da
CLI
gcluster.
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 doJobSet, encaminhar portas e ler registros de pods no GKE.
- Gravador do Artifact Registry
(
- 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.
- Leitor do Artifact Registry
(
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_pythonpara 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 bibliotecacloudpickle. - O contêiner
pathways-proxy(no podpathways-head): recebe a função serializada por gRPC e a encaminha para o contêinerpathways-workernas VMs de worker que possuem os dispositivos de CPU de entrada da chamada. Transmitir a flag--sidecar_name=externalconfigura o contêinerpathways-proxypara segmentar o contêinercolocated-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 volumeemptyDircompartilhado 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:
- Roteamento de funções: o módulo
jax.experimental.colocated_pythonempacota a função em um programa Interim Framework Runtime (IFRT) e a envia para o contêinerpathways-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. - Execução de memória compartilhada: o contêiner
pathways-workergrava fragmentos de entrada no volume compartilhado na memória (/tmp/sidecarou/tmp/shared-memory) e invoca o contêinercolocated-python-sidecarpor 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.Arrayfragmentados 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_classno worker. - Recriar o estado
@colocated_python_classapó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, comojax-0.12.0.1.YYYYMMDD-jax_JAX_VERSION: uma tag de build com carimbo de data/hora, como20261110-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:
Em um diretório de build vazio, crie um arquivo
requirements.txtpara seus pacotes extras. Omita os pacotesjaxejaxlib, que já estão instalados e fixados no arquivo/opt/venv/server_constraints.txt:grainCrie um
Dockerfileque instale os pacotes no arquivorequirements.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 cleanMantenha as instruções
ENTRYPOINTeCMDda imagem de base inalteradas. Se o arquivorequirements.txtinstalar pacotes de URLs do Git, adicione a seguinte instruçãoRUNantes da instruçãouv pip installRUN, porque a imagem de base slim omite a ferramentagit:RUN apt-get update && \ apt-get install -y --no-install-recommends git && \ rm -rf /var/lib/apt/lists/*Autentique o Docker na região do Artifact Registry usando o comando
gcloud auth configure-docker:gcloud auth configure-docker REGISTRY_LOCATION-docker.pkg.devSubstitua
REGISTRY_LOCATIONpelo local do Artifact Registry, comousouus-central1.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, como0.12.0.1.REGISTRY_LOCATION: o local do Artifact Registry, comousouus-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:
Gere um manifesto
JobSet(pathways-colocated-jobset.yaml) com uma das seguintes ferramentas:- O builder Python
pathways-utils: configure umJobSetcom o builderPathwaysJobSetchamando os métodos.add_colocated_python("SIDECAR_IMAGE")e.export_yaml("pathways-colocated-jobset.yaml"). Se você usar o pacotepathwaysutils(versão0.1.14ou anterior do PyPI), também transmita o argumentoproxy_container_kwargs={"args": ["--sidecar_name=external"]}para o construtorPathwaysJobSetou instale o pacotepathways-utilsda ramificaçãomain. - Cluster Toolkit (
gcluster): execute o comandogcluster job submitcom a flag--pathways-colocated-python-sidecar-imagee anexe a flag--dry-run-out=pathways-colocated-jobset.yamlpara renderizar o manifesto localmente sem enviar o job.
Substitua
SIDECAR_IMAGEpelo URI da imagem de arquivo secundário personalizada ou pelo URI da imagem pré-criadacolocated_python_sidecar.Os dois geradores configuram o manifesto para fazer o seguinte:
- Execute o contêiner
colocated-python-sidecarno campoinitContainerscomrestartPolicy: Alwaysem cada pod de worker. A CLIgclusternomeia o job replicado do worker comoworker, enquanto o builderPathwaysJobSeto nomeia comopathways-worker. - Transmita a flag
--sidecar_name=externalpara o contêinerpathways-proxye conecte o contêinerpathways-workerao arquivo secundário por TCP de loopback emlocalhost:50051. Quando o contêinerpathways-proxyé executado no campoinitContainers, ele também usarestartPolicy: Always. - Monte um volume
emptyDirna memória commedium: Memorynos dois contêineres de pod de worker: em/tmp/sidecarnos manifestosgclusterou em/tmp/shared-memorynos manifestosPathwaysJobSet. Os dois geradores também definem a variável de ambienteCLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORYno arquivo secundário e a flag--cloud_pathways_sidecar_shm_directoryno contêinerpathways-worker.
- O builder Python
Aplique o manifesto
JobSete aguarde até que os pods alcancem o statusRunning:kubectl apply -f pathways-colocated-jobset.yaml kubectl get pods -l jobset.sigs.k8s.io/jobset-name=JOBSET_NAMESubstitua
JOBSET_NAMEpelo valormetadata.namedoJobSet.
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: {}chamadosidecar-socketem/socknos contêinerespathways-workerecolocated-python-sidecar. - Defina
args: ["--unix_domain_socket_path=/sock/sidecar.sock"]e umexecstartupProbe(test -S /sock/sidecar.sock) no contêinercolocated-python-sidecar. - Anexe a flag
--cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sockao campoargsdo contêinerpathways-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, como0.12.0.1.SIDECAR_IMAGE: o URI da imagem de arquivo secundário personalizada ou pré-criada.WORKLOAD: um nome exclusivo deJobSet(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, como1.COMPUTE_TYPE: o tipo de máquina do Cloud TPU, comoct5lp-hightpu-4touct6e-standard-4t.TOPOLOGY: a topologia da fração da Cloud TPU, como4x8ou2x4.
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-headem vez de uma implantação headless, substitua a flag--pathways-headlesspelas flags--image="CLIENT_IMAGE"e--command="COMMAND". Use uma imagem de cliente JAX do Python 3.12 criada com pinsserver_constraints.txte transmita o comando de entrada (comopython colocated_example.py). - Renderização de manifesto local: anexe a
flag
--dry-run-out=pathways-colocated-jobset.yamlpara renderizar o manifestoJobSetlocalmente sem enviá-lo. - Sessões headless subsequentes: execute o comando
gcluster job cancele 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:
Para alinhar as dependências de serialização com a imagem do arquivo secundário, extraia o arquivo
/opt/venv/server_constraints.txte 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 pathwaysutilsSubstitua
JAX_VERSIONpela versão do JAX, como0.12.0.1.Se você executar o cliente fora do pod
pathways-head, encaminhe a porta local29000para o contêinerpathways-proxyem 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:29000Substitua
JOBSET_NAMEpelo valormetadata.namedoJobSet(ou o nomeWORKLOADque você transmitiu ao comandogcluster job submit).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}" )Execute o script no servidor proxy do IFRT:
JAX_PLATFORMS=proxy JAX_BACKEND_TARGET=grpc://127.0.0.1:29000 \ python colocated_example.pyO resultado será o seguinte:
TPU devices: 8, colocated CPU devices: 8 Transferred 8 arrays of shape (1024, 1024) to TPU HBM; sample sum=1048576.0Em cargas de trabalho de produção de várias frações, transmita um argumento
jax.Arrayfragmentado colocado nos dispositivos retornados pela chamadacolocated_python.colocated_cpu_devices(mesh)e defina o parâmetroout_specs_fncom 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
workercom a variável de ambienteJAX_PLATFORMS=cpu, porque essa configuração executa o JAX localmente em uma CPU e ignora o Pathways. Ignore qualquer mensagemIFRT proxy server disconnected: CANCELLEDexibida ao sair.
Para mais padrões de uso, consulte os seguintes recursos:
- Notebook Python colocalizado do JAX:
especialização de função e objetos
@colocated_python_classcom estado - Módulo MaxText
multihost_dataloading.py: pipeline de entrada de vários hostsRemoteIteratorque usa o Python colocalizado. - Checkpoints do Orbax Pathways e checkpoints de vários níveis com o Pathways: checkpoints distribuídos em sidecars de worker com a chamada
orbax.checkpoint.pathways.register_type_handlers(checkpointing_impl=CheckpointingImpl.COLOCATED_PYTHON)(ou a configuraçãocolocated_python_checkpointing=Trueno MaxText) e a opçãouse_colocated_python=Truepara checkpoints de vários níveis.
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:
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-sidecarSubstitua
JOBSET_NAMEpelo valormetadata.namedoJobSet(ou o nomeWORKLOADque você transmitiu ao comandogcluster job submit). Se você gerou o manifesto com o builderPathwaysJobSet, definareplicatedjob-name=pathways-workerna variávelROLE_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_sidecarConfirme 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 builderPathwaysJobSetusam o diretório/tmp/shared-memory, e as implantações do UDS registramunix:/sock/sidecar.sockem vez delocalhost:50051.Inspecione os registros do contêiner
pathways-workerno 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:50051Confirme se o contêiner
pathways-workerativou 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 compartilhadaemptyDirno caminho correspondente (/tmp/sidecarou/tmp/shared-memory) nos contêinerespathways-workerecolocated-python-sidecar.Timed out connecting to sidecar gRPC serviceouFailed to connect to external sidecar: confirme se o contêinercolocated-python-sidecaré executado no campoinitContainerscomrestartPolicy: Alwayse se as três imagenscloud-pathwaysusam tags correspondentes. Verifique se as configurações de TCP (--port=50051) ou UDS (volume/socke--unix_domain_socket_path=/sock/sidecar.sock) correspondem entre os contêinerespathways-proxyecolocated-python-sidecar.- Host do worker sem memória após grandes bursts de matriz: defina a
flag
--pathways_sidecar_shared_memory_idle_release_secs=0no contêinercolocated-python-sidecar(ao lado da flag--port=50051ou--unix_domain_socket_path) e a flag--cloud_pathways_shared_memory_idle_release_secs=0no contêinerpathways-worker. Definir as duas sinalizações como0libera 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 recursoJobSet:kubectl delete jobset JOBSET_NAMESubstitua
JOBSET_NAMEpelo valormetadata.namedoJobSet.Cluster Toolkit: cancele o job implantado:
gcluster job cancel WORKLOAD \ --cluster=CLUSTER \ --project=PROJECT_ID \ --location=LOCATIONSubstitua:
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.