Todos os produtos
Search
Central de documentação

MaxCompute:PyODPS

Última atualização: Jun 27, 2026

PyODPS é o SDK do MaxCompute para Python. Ele oferece uma interface de programação simples e prática para escrever jobs do MaxCompute, consultar tabelas e visualizações e gerenciar recursos usando Python. O PyODPS fornece funcionalidades semelhantes às da ferramenta de linha de comando ODPS, como upload e download de arquivos, criação de tabelas e execução de consultas ODPS SQL, além de recursos avançados, como envio de tarefas MapReduce e uso de UDFs do ODPS. Este tópico descreve os cenários de aplicação, as ferramentas compatíveis e as precauções importantes durante o uso do PyODPS.

Visão geral dos recursos

Os cenários de aplicação do PyODPS incluem:

Ferramentas compatíveis

Use o PyODPS em ambientes locais, no DataWorks ou nos PAI Notebooks.

Importante

Independentemente da ferramenta, evite baixar conjuntos completos de dados para o ambiente local e executar tarefas PyODPS diretamente nessa configuração. Essa prática consome muita memória e frequentemente causa erros OOM. Envie as tarefas para execução distribuída no MaxCompute. Para mais detalhes, consulte a seção Precauções: Não baixe todos os dados para o ambiente local e execute o PyODPS abaixo.

  • Ambiente local: instale e use o PyODPS em sua máquina. Para instruções detalhadas, consulte Uso do PyODPS em ambiente local.

  • DataWorks: os nós PyODPS no DataWorks já vêm com o pacote PyODPS pré-instalado. Desenvolva e execute periodicamente tarefas PyODPS diretamente nesses nós. Para orientações, consulte Uso do PyODPS no DataWorks.

  • PAI Notebooks: o ambiente Python do PAI também suporta a instalação e execução do PyODPS. As imagens integradas do PAI já incluem o PyODPS pronto para uso, inclusive em componentes Python personalizados no PAI-Designer. A utilização nos PAI Notebooks segue essencialmente o padrão geral. Consulte Visão geral das operações básicas e DataFrame (não recomendado).

Precauções: Não baixe todos os dados para o ambiente local e execute o PyODPS

O PyODPS, como SDK, executa em diversos clientes, incluindo PCs, nós PyODPS de desenvolvimento de dados no DataWorks ou ambientes de execução dos PAI Notebooks. pyodps环境 O PyODPS oferece várias operações práticas para trazer dados ao ambiente local, como downloads via tunnel, operações execute e to_pandas. Por isso, muitos usuários iniciantes tentam puxar os dados para a máquina local, processá-los e depois fazer o upload de volta ao MaxCompute. Na maioria dos casos, essa abordagem é altamente ineficiente, pois elimina completamente a vantagem da capacidade de processamento paralelo em larga escala do MaxCompute.

Método de processamento de dados

Descrição

Cenário de exemplo

Processamento local após download (não recomendado, risco de OOM)

Os nós PyODPS no DataWorks, por exemplo, incluem o pacote PyODPS e o ambiente Python necessário, mas funcionam como contêineres de execução cliente com recursos bastante limitados. Eles não utilizam recursos de computação do MaxCompute e possuem restrições rigorosas de memória.

O PyODPS disponibiliza a interface to_pandas, que converte dados do MaxCompute diretamente em estruturas Pandas DataFrame. No entanto, use essa interface apenas para obter pequenos volumes de dados destinados a desenvolvimento e depuração locais, nunca para processamento em massa. Seu uso aciona o download de grandes quantidades de dados do MaxCompute para o ambiente local. Se as operações subsequentes forem realizadas exclusivamente em DataFrames locais, você perde a capacidade de computação paralela em larga escala do MaxCompute. Além disso, mesmo com volumes moderados de dados, a memória de uma única máquina pode facilmente esgotar, resultando em erro OOM.

Execução distribuída enviada ao MaxCompute (recomendado)

Utilize adequadamente a funcionalidade distribuída de DataFrame do PyODPS. Envie as principais cargas de computação para execução distribuída no MaxCompute, em vez de baixar e processar dados no nó cliente PyODPS. Essa é a chave para usar o PyODPS corretamente.

Nota

Para converter resultados de execução SQL em DataFrame, salve primeiro esses resultados em uma tabela do MaxCompute usando a instrução CREATE TABLE AS SELECT ... e só então faça a conversão.

Prefira a interface PyODPS DataFrame para processar dados. Necessidades comuns, como transformar cada linha de dados e gravá-la de volta na tabela ou dividir uma linha em várias, podem ser atendidas com map ou apply do PyODPS DataFrame. Algumas dessas operações exigem apenas uma linha de código, garantindo eficiência e simplicidade. Veja exemplos em Uso de funções personalizadas.

Essas interfaces são traduzidas automaticamente em SQL e executadas como computação distribuída no cluster do MaxCompute. Assim, o consumo de memória local é praticamente zero, proporcionando ganhos expressivos de desempenho em comparação com o processamento em uma única máquina.

A seguir, apresentamos um exemplo de segmentação de texto para comparar o código das duas abordagens.

  • Cenário de exemplo

    Um usuário precisa analisar strings de log geradas diariamente para extrair informações específicas. Existe uma tabela com apenas uma coluna do tipo string. Com a biblioteca jieba, é possível segmentar frases em chinês, identificar palavras-chave desejadas e armazená-las em uma tabela de informações.

  • Exemplo de código ineficiente

    import jieba
    t = o.get_table('word_split')
    out = []
    with t.open_reader() as reader:
        for r in reader:
            words = list(jieba.cut(r[0]))
            #
            # 处理逻辑,产生出 processed_data
            #
            out.append(processed_data)
    out_t = o.get_table('words')
    with out_t.open_writer() as writer:
        writer.write(out)

    Mentalidade de processamento de dados em máquina única: leitura linha a linha, processamento individual e gravação sequencial na tabela de destino. Durante todo o fluxo, o download e o upload de dados consomem muito tempo. Além disso, a máquina que executa o script precisa de grande quantidade de memória para lidar com todos os dados. Usuários de nós DataWorks, em particular, enfrentam alto risco de erros OOM por ultrapassarem o limite de memória alocado por padrão.

  • Exemplo de código eficiente

    from odps.df import output
    out_table = o.get_table('words')
    df = o.get_table('word_split').to_df()
    
    # 假定需要返回的字段及类型如下
    out_names = ["word", "count"]
    out_types = ["string", "int"]
    
    @output(out_names, out_types)
    def handle(row):
        import jieba
        words = list(jieba.cut(row[0]))
        #
        # 处理逻辑,产生出 processed_data
        #
        yield processed_data
    df.apply(handle, axis=1).persist(out_table.name)

    Implementação de execução distribuída utilizando apply:

    • Toda a lógica complexa reside na função handle. Essa função é serializada automaticamente e enviada ao servidor para uso como UDF, sendo executada remotamente. Como a execução no servidor também processa cada linha individualmente, não há diferença lógica. A vantagem é que, ao enviar o programa para execução no MaxCompute, várias máquinas processam os dados simultaneamente, economizando tempo significativo.

    • A chamada à interface persist grava os dados gerados diretamente em outra tabela do MaxCompute. Tanto a produção quanto o consumo dos dados ocorrem inteiramente dentro do cluster MaxCompute, poupando rede e memória locais.

    • Este exemplo também utiliza pacotes de terceiros. O MaxCompute permite o uso desses pacotes em funções personalizadas (como jieba no exemplo). Portanto, não se preocupe com custos de refatoração: aproveite a capacidade de computação em larga escala do MaxCompute sem precisar alterar a lógica principal do código.

Limites de uso