MaxCompute:Perguntas frequentes sobre o MaxFrame

Índice de códigos de erro

Problema 1: Erro "invalid type INT for function UDF definition, you need to defina odps.sql.type.system.odps2=true; to use it"

Os tipos de dados do MaxCompute V2.0 não estão habilitados por padrão. Se sua função definida pelo usuário (UDF) utilizar tipos da V2.0, como INT, o job falhará durante a execução.

Adicione a seguinte flag antes de chamar new_session:

from maxframe import config

config.options.sql.settings = {
    "odps.sql.type.system.odps2": "true"
}

Problema 2: Erro "UDF : No module named 'cloudpickle'"

O pacote cloudpickle está ausente no ambiente de execução. Referencie a imagem base do MaxCompute para incluí-lo:

from maxframe import config

config.options.sql.settings = {
    "odps.session.image": "common",
}

Problema 3: Como reutilizar recursos em uma UDF enviada por apply de DataFrame

Quando uma UDF precisa inicializar recursos custosos — como carregar um modelo de ML ou criar uma conexão com banco de dados —, a inicialização deve ocorrer apenas uma vez por worker, e não por linha.

O Python inicializa valores padrão de parâmetros somente uma vez por definição de função. Armazenar estado compartilhado em um argumento padrão mutável (como um dict) aproveita esse comportamento para garantir que a inicialização ocorra exatamente uma vez por worker da UDF.

O exemplo a seguir carrega um modelo YOLO apenas uma vez por worker:

def predict(s, _ctx={}):
    from ultralytics import YOLO
    # _ctx is initialized as an empty dict once per worker process.
    # On the first call, load the model and store it. Subsequent calls reuse it.
    if not _ctx.get("model", None):
        model = YOLO(os.path.join("./", "yolo11n.pt"))
        _ctx["model"] = model
    model = _ctx["model"]

    # Call the model APIs here.

Para recursos que exigem limpeza (como conexões de banco de dados), utilize uma classe personalizada com __init__ e __del__:

class MyConnector:

    def __init__(self):
        # Open the connection when the object is created.
        self.conn = create_connection()

    def __del__(self):
        # Close the connection when the object is garbage-collected.
        try:
            self.conn.close()
        except:
            pass

def process(s, connector=MyConnector()):
    # The connector is shared across all calls within this worker.
    # No need to open or close the connection inside the UDF.
    connector.conn.execute("xxxxx")

A inicialização ocorre uma vez por worker da UDF, e não globalmente. Se uma UDF processar 100.000 linhas distribuídas entre 10 workers, cada worker lidará com 10.000 linhas e executará a inicialização uma única vez, totalizando 10 execuções.

Problema 4: Como atualize a versão do MaxFrame em grupos de recursos do DataWorks (exclusivos e de uso geral)

Conteúdo em breve.

Problema 5: Melhores práticas para uso de imagens personalizadas do MaxFrame

Conteúdo em breve.

Problema 6: ODPS-0130071: Exceção de análise semântica — sequence_row_id não pode ser aplicado

Adicione index_col à chamada read_odps_table. Sem esse parâmetro, o MaxFrame não consegue atribuir IDs às linhas, causando falha no plano físico.

df2 = md.read_odps_table("tablename", index_col="column").to_pandas()
df2.reset_index(inplace=True)

Problema 7: Erro "Cannot determine dtypes by calculating with enumerate data, please especifique it as arguments" ao usar apply

O MaxFrame infere o tipo de retorno da UDF para validar e construir o DataFrame ou Series de saída. Essa inferência falha em duas situações:

• A UDF não execute no ambiente atual. Por exemplo, depende de uma imagem personalizada, de uma biblioteca de terceiros não instalada ou requer parâmetros de entrada indisponíveis durante a inferência.

• O tipo de retorno real não corresponde ao output_type especificado.

Especifique dtypes explicitamente para informar ao MaxFrame o retorno da UDF:

• Retornar um DataFrame com uma coluna int: df.apply(..., dtypes=pd.Series([np.int_]), output_type="dataframe")

• Retornar um DataFrame com as colunas A (int) e B (str): df.apply(..., dtypes={"A": np.int_, "B": np.str_}, output_type="dataframe")

• Retornar uma Series chamada flag com tipo bool: df.apply(..., dtype="bool", name="flag", output_type="series")

Problema 8: Como adicionar uma flag da mesma forma que no SQL

from maxframe import config

config.options.sql.settings = {
    "odps.stage.mapper.split.size": "8",   # Input split size for mappers, in MB
    "odps.stage.joiner.num": "20"           # Number of joiner instances
}

Problema 9: Como referenciar pacotes de terceiros no desenvolvimento com MaxFrame

Consulte Referenciar pacotes e imagens de terceiros para obter instruções completas.

Para referenciar um recurso do MaxCompute na UDF, utilize o decorador @with_resources:

from maxframe.udf import with_resources

@with_resources("resource_name")
def process(row):
    ...

Problema 10: Erro de tarefa "TypeError: Cannot accept arguments append_partitions"

Atualize o PyODPS para a versão 0.12.0 ou posterior:

pip install --upgrade pyodps

Problema 11: Como analisar vários campos de string JSON

O MaxFrame SDK V1.0.0 e versões posteriores suportam a análise de múltiplos campos de string JSON por meio de Series.mf.flatjson:

<https://maxframe.readthedocs.io/en/latest/reference/dataframe/generated/maxframe.dataframe.Series.mf.flatjson.html>

Problema 12: ODPS-0010000: Falha no job Fuxi — Job failed for unknown reason, cannot get jobstatus

Esse erro geralmente indica falha na instalação de dependências ao utilizar @with_python_requirements ou métodos similares. O nó PythonPack, responsável por instale dependências via pip, não conseguiu acessar o repositório, frequentemente devido a um problema transitório de rede.

Verifique o stderr no Logview do PythonPack para mais detalhes. Uma mensagem típica se parece com:

requests.exceptions.ConnectionError: HTTPConnectionPool(host='service.cn-beijing-intranet.maxcompute.aliyun-inc.com', port=80): Max retries exceeded with url: ...
(Caused by NameResolutionError("Failed to resolve 'service.cn-beijing-intranet.maxcompute.aliyun-inc.com'"))

Para corrigir:

1. Tente execute o job novamente. Se um problema temporário de rede causou o erro, tentar novamente geralmente resolve. Caso persista, entre em contato com a equipe do MaxFrame.

2. Armazene em cache o resultado do empacotamento para jobs periódicos. Assim que o PythonPack for concluído com sucesso, armazene o resultado em cache para que os jobs diários subsequentes pulem a etapa de instalação:

   from maxframe import options
   
   # Subsequent jobs reuse the cached PythonPack result instead of reinstalling.
   options.pythonpack.task.settings = {"odps.pythonpack.production": "true"}

   Para forçar uma nova compilação ignorando o cache, adicione force_rebuild=True em @with_python_requirements.

3. Empacote as dependências offline. Evite o uso do PythonPack empacotando as dependências offline com o PyODPS-Pack, fazendo upload delas como recurso do MaxFrame e referenciando-as no job. O PyODPS-Pack compila pacotes em um contêiner docker manylinux para evitar problemas de compatibilidade. Ele execute em máquinas Linux X86; dispositivos Apple com chips ARM da série M não são suportados. Após o upload, referencie o recurso na UDF com @with_resources.

Problema 13: ODPS-0123055: Exceção de script do usuário

Este é o erro mais comum no MaxFrame. Ele ocorre quando uma UDF gera uma exceção Python durante a execução de operadores como apply, apply_chunk, flatmap, map ou transform.

Como interpretar o erro

Verifique o stderr da instância que falhou. O stack trace aponta diretamente para a linha onde ocorreu a falha. Por exemplo, chamar json.loads em uma string não JSON gera a saída abaixo. A mensagem identifica simple_failure na linha 5 como a source:

ODPS-0123055:User script exception - Traceback (most recent call last):
  ...
  File "...", line 5, in simple_failure
  File ".../json/__init__.py", line 346, in loads
    return _default_decoder.decode(s)
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Se a UDF depender de uma biblioteca não instalada no ambiente de execução, ela não poderá ser desserializada. A mensagem de erro indicará o nome do módulo ausente:

ModuleNotFoundError: No module named 'xxhash'

Causas comuns e soluções

Depuração local

Reproduza o erro construindo uma entrada de amostra e chamando a função como uma função Python comum:

def udf_func(row):
    import json

    text = row["json_text"]
    data = json.loads(text)
    return data

# Test locally with sample data
udf_func(pd.Series(['{"hello": "maxframe"}'], index=["json_text"]))

Problema 14: ODPS-0123144: Falha no job Fuxi — kInstanceMonitorTimeout CRASH_EXIT

A UDF atingiu o tempo limite. Na computação offline do MaxCompute, a execução da UDF é monitorada por lotes de linhas. Se a UDF não concluir o processamento de um lote dentro do limite de tempo configurado, o job será encerrado.

Ajuste o tamanho do lote e o timeout conforme necessário:

from maxframe import options

options.sql.settings = {
    # Number of rows per batch. Default: 1024. Minimum: 1.
    # Reduce this if individual rows take a long time to process.
    "odps.sql.executionengine.batch.rowcount": "1",
    # Time limit per batch, in seconds. Default: 1800. Maximum: 3600.
    "odps.function.timeout": "3600",
}

Problema 15: ODPS-0123144: Falha no job Fuxi — Job exceed live limit

Por padrão, os jobs do MaxCompute têm tempo máximo de execução de 24 horas. Quando um job ultrapassa esse limite, o sistema de mapeamento CDN o marca como Failed e o encerra.

Se o job for executado no DataWorks, um timeout diferente pode ser aplicado e o status do job aparecerá como Canceled. Entre em contato com a equipe do DataWorks para mais detalhes.

Aumente os limites de tempo da sessão e do job antes de enviar jobs de longa duração:

from maxframe import options

# Extend the maximum session lifetime (in seconds)
options.session.max_alive_seconds = 72 * 60 * 60
# Extend the maximum session idle time (in seconds)
options.session.max_idle_seconds = 72 * 60 * 60
options.sql.settings = {
    # Maximum SQL job runtime in hours. Default: 24. Maximum: 72.
    "odps.sql.job.max.time.hours": 72,
}

Problema 16: ODPS-0130071: Exceção de análise semântica — unable to retrieve row count of file pangu://xxx

Esse erro ocorre quando o MaxCompute não consegue ler os metadados de contagem de linhas de uma tabela de origem. Geralmente, isso acontece porque nenhum arquivo de metadados foi gerado quando os dados foram gravados na tabela. Sem esses metadados, o MaxCompute não consegue dividir a tabela com precisão para processamento distribuído.

Opção 1: Utilize odps.stage.mapper.split.size em vez de odps.sql.split.dop. Essa flag controla o tamanho da divisão em MB (padrão: 256, mínimo: 1) e não depende dos metadados de contagem de linhas.

Opção 2: Se você precisar de uma divisão precisa, entre em contato com a equipe do MaxCompute para regenerar o arquivo de metadados compactos (CMF).

Para garantir que arquivos de metadados sejam gerados em futuras operações de gravação, adicione estas flags:

from maxframe import options

options.sql.settings = {
    "odps.task.merge.enabled": "false",
    "odps.sql.reshuffle.dynamicpt": "false",
    "odps.sql.enable.dynaparts.stats.collection": "true",
    "odps.optimizer.dynamic.partition.is.first.nth.value.split.enable": "false",
    "odps.sql.stats.collection.aggressive": "true",
}

Problema 17: ODPS-0130071:[x,y] Exceção de análise semântica

Em um cenário de ReadOdpsQuery, esse erro geralmente indica um problema semântico na própria consulta SQL.

1. Verifique a sintaxe do SQL.

2. Atualize o cliente MaxFrame: pip install --upgrade maxframe.

3. Se o erro persistir, entre em contato com a equipe do MaxFrame.

Problema 18: ODPS-0020041:StringOutOfMaxLength:String length X is larger than maximum Y

Uma string nos seus dados excede o limite da camada de armazenamento do MaxCompute, que é de 268.435.456 caracteres. Isso pode acontecer ao gravar em uma tabela ou durante uma operação de shuffle.

Opção 1: Filtre ou trunque os dados excessivamente grandes. Em um ReadOdpsQuery, utilize a função LENGTH para filtrar linhas antes que elas atinjam o limite.

Opção 2: Compacte os dados antes de armazená-los. O gzip pode reduzir significativamente o tamanho da string:

import gzip

def compress_string(input_string):
    """Compresses a string using gzip."""
    encoded_string = input_string.encode('utf-8')
    compressed_bytes = gzip.compress(encoded_string)
    return compressed_bytes

Opção 3: Entre em contato com a equipe do MaxCompute para obter ajuda com dados específicos.

Problema 19: ODPS-0010000:System internal error — fuxi job failed, caused by: process exited with code 0

Um job contendo uma UDF ou função de IA falhou devido a um erro de memória insuficiente (OOM).

1. Entre em contato com a equipe do MaxCompute para confirme o uso real de memória.

2. Execute a UDF ou função de IA com mais memória. Para uma UDF, utilize @with_running_options:

   @with_running_options(memory="8GB")
   def udf_func(row):
       return row

   Para uma função de IA, passe running_options={"memory": "8GB"} na chamada da função.

Problema 20: ODPS-0123131:User defined function exception — internal error — Fatal Error Happended

Esse erro ocorre ao ler ou gravar em uma tabela externa. Entre em contato com a equipe do MaxCompute.

Problema 21: ODPS-0010000:System internal error — MetastoreServerException: 0420111:Database not found

O schema, projeto ou tabela referenciado no seu SQL não foi encontrado no armazenamento de metadados.

1. Verifique se os nomes do projeto, schema e tabela no seu SQL estão corretos. Corrija quaisquer erros e tente novamente.

2. Se as informações estiverem corretas e o erro persistir, entre em contato com a equipe do MaxCompute.

Problema 22: ODPS-0010000:System internal error — fuxi job failed, caused by: process killed by signal 7

A UDF enviou um sinal anormal durante a execução.

1. Verifique se a UDF envia algum sinal ao processo (por exemplo, para cancelamento ou tratamento de timeout).

2. Se nenhum sinal for enviado pelo seu código, entre em contato com a equipe do MaxCompute para solução de problemas.

Problema 23: ODPS-0010000:System internal error — fuxi job failed, caused by: StdException:vector::_M_range_insert

A UDF não conseguiu alocar memória suficiente, causando falha na inserção em vetor.

1. Verifique se há problemas de memória na UDF. Confirme se todas as bibliotecas de dependência nativas estão atualizadas e livres de bugs conhecidos de memória. Aumente a memória alocada para a UDF.

2. Se o problema persistir, entre em contato com a equipe do MaxCompute.

Problema 24: ODPS-0130071: Exceção de análise semântica — task:M1 instance count exceeds limit 99999

Por padrão, o MaxCompute divide as tabelas de origem em blocos de 256 MB para processamento distribuído. Se o número total de blocos exceder 99.999, o job falhará. Isso acontece quando a tabela de origem é muito grande ou quando uma flag de divisão está mal configurada.

1. Aumente o tamanho da divisão com odps.stage.mapper.split.size (unidade: MB, padrão: 256, mínimo: 1). Um valor maior reduz o número de blocos.

2. Defina uma contagem alvo de blocos com odps.sql.split.dop (mínimo: 1).

3. Se nenhuma das abordagens funcionar após múltiplos ajustes, entre em contato com a equipe do MaxCompute. Devido a restrições internas, a contagem final de blocos pode diferir do alvo. Definir o alvo próximo ao limite de 99.999 ainda pode acionar o erro.

Problema 25: ODPS-0110061:Failed to run ddltask — ODPS-0130131:Table not found

Esse erro aparece em jobs do MaxFrame de longa duração (mais de 24 horas). Uma tarefa interna de linguagem de definição de dados (DDL) falha porque uma tabela temporária criada anteriormente na sessão expirou.

Tabelas temporárias criadas durante a computação (por exemplo, após uma chamada df.execute()) têm um tempo de vida (TTL) padrão de um dia. Tabelas de destino especificadas com to_odps_table não são afetadas.

Aumente o TTL das tabelas temporárias para cobrir a duração esperada do job:

options.sql.settings = {
    # TTL in days. Set this to the maximum number of days your job may run.
    "session.temp_table_lifecycle": 3,
}

Problema 26: NoTaskServerResponseError

A sessão do MaxFrame expirou. Por padrão, uma sessão expira após 1 hora de inatividade. Se você pausar em um Jupyter Notebook por mais de 1 hora antes de execute a próxima célula, a sessão será perdida.

Se você já encontrou esse erro: Recrie a sessão. O estado de computação das células anteriores não é preservado.

Para evitar esse erro em execuções futuras: Estenda o timeout de ociosidade antes de iniciar a sessão:

from maxframe import options

# Set the session idle timeout to 24 hours (default is 1 hour).
options.session.max_idle_seconds = 60 * 60 * 24

Problema 27: IntCastingNaNError: Cannot convert non-finite values (NA or inf) to integer: Error while type casting for column 'xx'

Esse erro aparece ao imprimir um DataFrame que contém uma coluna BIGINT ou INT com valores NULL ou INF, incluindo a exibição automática em uma célula do Jupyter Notebook. O problema subjacente é que o pandas não consegue representar NULL em colunas inteiras. Valores NULL são armazenados internamente como FLOAT, e a conversão de volta para inteiro falha.

A equipe do MaxFrame está trabalhando em uma correção definitiva. Por enquanto, utilize uma destas soluções alternativas:

1. Preencha os valores NULL antes de imprimir: df["col"].fillna(0)

2. Converta a coluna para float antes de imprimir: df["col"].astype(float)

3. Evite imprimir a coluna, a menos que seja necessário.

Problema 28: ODPS-0010000:System internal error — fuxi job failed, SQL job failed after failover for too many times

Os dados de shuffle são muito grandes, causando falta de memória (OOM) no Job Master. Isso geralmente acontece quando um job com operações Reduce ou Join gera muitas instâncias mapper ou reducer/joiner.

Gatilhos comuns:

• Valor de split.size muito pequeno ou split.dop muito grande, criando excesso de instâncias mapper

• Valor de reducer.num ou joiner.num elevado, criando excesso de instâncias reducer ou joiner

Reduza o número de mappers e reducers/joiners. O total combinado não deve exceder 10.000. Se o erro persistir, entre em contato com a equipe do MaxCompute.

Problema 29: ODPS-0010000:System internal error — Total resource size must be <= 2048MB

Uma UDF depende de recursos cujo tamanho combinado excede o limite de 2048 MB.

Utilize a aceleração de volume externo para baixe os recursos do Object Storage Service (OSS) em tempo de execução. Essa abordagem evita a restrição de 2048 MB e oferece velocidades de download mais rápidas.

Problema 30: ODPS-0130071: Exceção de análise semântica — column values_list in source has incompatible type ARRAY/MAP/STRUCT

Os dados contêm arrays, maps ou structs, e a declaração de tipo não corresponde.

1. Atualize o cliente MaxFrame e tente novamente: pip install -U maxframe.

2. Se o erro persistir, entre em contato com a equipe do MaxFrame. Pode ser um bug no sistema de tipos do MaxFrame.

Problema 31: Saída de shuffle muito grande

Utilize a flag odps.sql.sys.flag.fuxi_JobMaxInternalFolderSize para especifique o espaço máximo de shuffle em MB.