MaxCompute:Foire aux questions sur MaxFrame

Index des codes d'erreur

Problème 1 : Erreur « invalid type INT for function UDF definition, you need to set odps.sql.type.system.odps2=true; to use it »

Les types de données MaxCompute V2.0 ne sont pas activés par défaut. Lorsque votre fonction définie par l'utilisateur (UDF) utilise des types V2.0 tels que INT, le travail échoue lors de l'exécution.

Ajoutez l'indicateur suivant avant d'appeler new_session :

from maxframe import config

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

Problème 2 : Erreur « UDF : No module named 'cloudpickle' »

Le package cloudpickle est absent de l'environnement d'exécution. Référencez l'image de base MaxCompute pour l'inclure :

from maxframe import config

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

Problème 3 : Réutilisation des ressources dans une UDF soumise par une application DataFrame

Lorsqu'une UDF doit initialiser des ressources coûteuses, telles que le chargement d'un modèle d'apprentissage automatique ou la création d'une connexion à une base de données, il est préférable que l'initialisation ait lieu une fois par nœud de calcul et non une fois par ligne.

Python n'initialise les valeurs des paramètres par défaut qu'une seule fois par définition de fonction. En stockant l'état partagé dans un argument mutable par défaut (comme un dict), vous exploitez ce comportement afin que l'initialisation s'exécute exactement une fois par nœud de travail UDF.

L'exemple suivant charge un modèle YOLO une seule fois par nœud de travail :

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.

Pour les ressources nécessitant un nettoyage (telles que les connexions aux bases de données), utilisez une classe personnalisée avec __init__ et __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")

L'initialisation s'exécute une fois par nœud de travail UDF, et non une fois de manière globale. Si une UDF traite 100 000 lignes réparties sur 10 nœuds de travail, chaque nœud gère 10 000 lignes et exécute l'initialisation une fois ; l'initialisation est donc exécutée 10 fois au total.

Problème 4 : Mise à jour de la version MaxFrame dans les groupes de ressources DataWorks (exclusifs et à usage général)

Contenu à venir.

Problème 5 : Bonnes pratiques pour l'utilisation des images personnalisées MaxFrame

Contenu à venir.

Problème 6 : ODPS-0130071 : Exception d'analyse sémantique — sequence_row_id ne peut pas être appliqué

Ajoutez index_col à votre appel read_odps_table. Sans cet élément, MaxFrame ne peut pas attribuer d'identifiants de ligne, ce qui entraîne l'échec du plan physique.

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

Problème 7 : Erreur « Cannot determine dtypes by calculating with enumerate data, please specify it as arguments » lors de l'utilisation de apply

MaxFrame déduit le type de retour de votre UDF pour valider et construire le DataFrame ou la Series de sortie. Cette inférence échoue dans deux situations :

• La UDF ne peut pas s'exécuter dans l'environnement actuel, par exemple parce qu'elle dépend d'une image personnalisée, d'une bibliothèque tierce non installée ou nécessite des paramètres d'entrée indisponibles lors de l'inférence.

• Le type de retour réel ne correspond pas à la valeur output_type que vous avez spécifiée.

Spécifiez explicitement dtypes pour indiquer à MaxFrame ce que renvoie la UDF :

• Renvoyer un DataFrame avec une colonne int : df.apply(..., dtypes=pd.Series([np.int_]), output_type="dataframe")

• Renvoyer un DataFrame avec les colonnes A (int) et B (str) : df.apply(..., dtypes={"A": np.int_, "B": np.str_}, output_type="dataframe")

• Renvoyer une Series nommée flag avec un type bool : df.apply(..., dtype="bool", name="flag", output_type="series")

Problème 8 : Ajout d'un indicateur comme dans 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
}

Problème 9 : Référence des packages tiers dans le développement MaxFrame

Consultez Référence des packages tiers et des images pour obtenir des instructions complètes.

Pour référencer une ressource MaxCompute dans votre UDF, utilisez le décorateur @with_resources :

from maxframe.udf import with_resources

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

Problème 10 : Erreur de tâche « TypeError: Cannot accept arguments append_partitions »

Mettez à jour PyODPS vers la version 0.12.0 ou ultérieure :

pip install --upgrade pyodps

Problème 11 : Analyse de nombreux champs de chaîne JSON

Le SDK MaxFrame V1.0.0 et versions ultérieures prend en charge l'analyse de plusieurs champs de chaîne JSON à l'aide de Series.mf.flatjson :

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

Problème 12 : ODPS-0010000 : Échec du travail Fuxi — Échec du travail pour une raison inconnue, impossible d'obtenir le statut du travail

Cette erreur signifie généralement que l'installation des dépendances a échoué lors de l'utilisation de @with_python_requirements ou de méthodes similaires. Le nœud PythonPack qui installe les dépendances pip n'a pas pu atteindre le dépôt de dépendances, souvent en raison d'un problème réseau transitoire.

Vérifiez la sortie stderr dans le Logview PythonPack pour plus de détails. Un message typique se présente comme suit :

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'"))

Pour résoudre ce problème :

1. Relancez le travail. Si l'erreur était causée par un problème réseau temporaire, une nouvelle tentative fonctionne généralement. Si le problème persiste, contactez l'équipe MaxFrame.

2. Mettez en cache le résultat de l'empaquetage pour les travaux périodiques. Une fois que PythonPack s'est terminé avec succès, mettez le résultat en cache afin que les travaux quotidiens suivants ignorent l'étape d'installation :

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

   Pour forcer une reconstruction et ignorer le cache, ajoutez force_rebuild=True dans @with_python_requirements.

3. Empaqueter les dépendances hors ligne. Évitez complètement PythonPack en empaquetant les dépendances hors ligne avec PyODPS-Pack, en les téléchargeant en tant que ressource MaxFrame et en les référençant dans le travail. PyODPS-Pack crée des packages dans un conteneur Docker manylinux pour éviter les problèmes de compatibilité. Il s'exécute sur des machines Linux X86 ; les appareils Apple équipés de puces ARM série M ne sont pas pris en charge. Après le téléchargement, référencez la ressource dans votre UDF avec @with_resources.

Problème 13 : ODPS-0123055 : Exception de script utilisateur

Il s'agit de l'erreur MaxFrame la plus courante. Elle se produit lorsqu'une UDF lève une exception Python lors de l'exécution d'opérateurs tels que apply, apply_chunk, flatmap, map ou transform.

Comment lire l'erreur

Vérifiez la sortie stderr de l'instance ayant échoué. La trace de la pile pointe directement vers la ligne qui a échoué. Par exemple, l'appel de json.loads sur une chaîne non JSON produit cette sortie — le message identifie simple_failure à la ligne 5 comme 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)

Si la UDF dépend d'une bibliothèque qui n'est pas installée dans l'environnement d'exécution, elle ne peut pas être désérialisée. Le message d'erreur indique le module manquant :

ModuleNotFoundError: No module named 'xxhash'

Causes courantes et correctifs

Débogage local

Reproduisez l'erreur en construisant un exemple d'entrée et en appelant la fonction comme une fonction Python régulière :

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"]))

Problème 14 : ODPS-0123144 : Échec du travail Fuxi — kInstanceMonitorTimeout CRASH_EXIT

Le délai d'attente de la UDF a été dépassé. Dans le calcul hors ligne MaxCompute, l'exécution de la UDF est surveillée par lots de lignes ; si une UDF ne termine pas le traitement d'un lot dans le délai configuré, le travail est arrêté.

Ajustez la taille du lot et le délai d'attente selon vos besoins :

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",
}

Problème 15 : ODPS-0123144 : Échec du travail Fuxi — Job exceed live limit

Par défaut, les travaux MaxCompute ont une durée d'exécution maximale de 24 heures. Lorsqu'un travail dépasse cette limite, le système de mappage CDN le marque comme ayant échoué et l'arrête.

Si le travail s'exécute sur DataWorks, un délai d'attente différent peut s'appliquer et l'état du travail s'affiche comme Annulé. Contactez l'équipe DataWorks pour plus de détails.

Augmentez les limites de temps de session et de travail avant de soumettre des travaux de longue durée :

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,
}

Problème 16 : ODPS-0130071 : Exception d'analyse sémantique — impossible de récupérer le nombre de lignes du fichier pangu://xxx

Cette erreur se produit lorsque MaxCompute ne peut pas lire les métadonnées du nombre de lignes pour une table source, généralement parce qu'aucun fichier méta n'a été généré lors de l'écriture des données dans la table. Sans ces métadonnées, MaxCompute ne peut pas diviser précisément la table pour un traitement distribué.

Option 1 : Utilisez odps.stage.mapper.split.size au lieu de odps.sql.split.dop. Cet indicateur contrôle la taille de division en Mo (par défaut : 256, minimum : 1) et ne dépend pas des métadonnées du nombre de lignes.

Option 2 : Si vous avez besoin d'une division précise, contactez l'équipe MaxCompute pour régénérer le fichier méta compact (CMF).

Pour garantir la génération de fichiers méta lors des futures opérations d'écriture, ajoutez ces indicateurs :

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",
}

Problème 17 : ODPS-0130071:[x,y] Exception d'analyse sémantique

Dans un scénario ReadOdpsQuery, cette erreur indique généralement un problème sémantique dans la requête SQL elle-même.

1. Vérifiez la syntaxe SQL.

2. Mettez à niveau le client MaxFrame : pip install --upgrade maxframe.

3. Si l'erreur persiste, contactez l'équipe MaxFrame.

Problème 18 : ODPS-0020041:StringOutOfMaxLength:La longueur de la chaîne X est supérieure au maximum Y

Une chaîne de vos données dépasse la limite de la couche de stockage MaxCompute de 268 435 456 caractères. Cela peut se produire lors de l'écriture dans une table ou pendant une opération de brassage.

Option 1 : Filtrez ou tronquez les données trop volumineuses. Dans une requête ReadOdpsQuery, utilisez la fonction LENGTH pour filtrer les lignes avant qu'elles n'atteignent la limite.

Option 2 : Compressez les données avant de les stocker. gzip peut réduire considérablement la taille des chaînes :

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

Option 3 : Contactez l'équipe MaxCompute pour obtenir de l'aide concernant des données spécifiques.

Problème 19 : ODPS-0010000:Erreur interne du système — échec du travail fuxi, causé par : process exited with code 0

Un travail contenant une UDF ou une fonction IA a échoué en raison d'une erreur d'épuisement de la mémoire (OOM).

1. Contactez l'équipe MaxCompute pour confirmer l'utilisation réelle de la mémoire.

2. Exécutez la UDF ou la fonction IA avec plus de mémoire. Pour une UDF, utilisez @with_running_options :

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

   Pour une fonction IA, transmettez running_options={"memory": "8GB"} dans l'appel de fonction.

Problème 20 : ODPS-0123131:Exception de fonction définie par l'utilisateur — erreur interne — Fatal Error Happended

Cette erreur se produit lors de la lecture ou de l'écriture dans une table externe. Contactez l'équipe MaxCompute.

Problème 21 : ODPS-0010000:Erreur interne du système — MetastoreServerException: 0420111:Database not found

Le schéma, le projet ou la table référencé dans votre SQL est introuvable dans le magasin de métadonnées.

1. Vérifiez que les noms de projet, de schéma et de table dans votre SQL sont corrects. Corrigez les erreurs et réessayez.

2. Si les informations sont correctes et que l'erreur persiste, contactez l'équipe MaxCompute.

Problème 22 : ODPS-0010000:Erreur interne du système — échec du travail fuxi, causé par : process killed by signal 7

La UDF a envoyé un signal anormal pendant l'exécution.

1. Vérifiez si la UDF envoie des signaux au processus (par exemple, pour l'annulation ou la gestion des délais d'attente).

2. Si aucun signal n'est envoyé depuis votre code, contactez l'équipe MaxCompute pour le dépannage.

Problème 23 : ODPS-0010000:Erreur interne du système — échec du travail fuxi, causé par : StdException:vector::_M_range_insert

La UDF n'a pas pu allouer suffisamment de mémoire, ce qui a entraîné l'échec de l'insertion dans un vecteur.

1. Vérifiez la UDF pour détecter les problèmes de mémoire. Assurez-vous que toutes les bibliothèques de dépendances natives sont à jour et ne présentent pas de bogues de mémoire connus. Augmentez la mémoire allouée à la UDF.

2. Si le problème persiste, contactez l'équipe MaxCompute.

Problème 24 : ODPS-0130071 : Exception d'analyse sémantique — task:M1 instance count exceeds limit 99999

Par défaut, MaxCompute divise les tables sources en morceaux de 256 Mo pour un traitement distribué. Si le nombre total de morceaux dépasse 99 999, le travail échoue. Cela se produit lorsque la table source est très volumineuse ou lorsqu'un indicateur de division est mal configuré.

1. Augmentez la taille de division avec odps.stage.mapper.split.size (unité : Mo, par défaut : 256, minimum : 1). Une valeur plus élevée réduit le nombre de morceaux.

2. Définissez un nombre cible de morceaux avec odps.sql.split.dop (minimum : 1).

3. Si aucune approche ne fonctionne après plusieurs ajustements, contactez l'équipe MaxCompute. En raison de contraintes internes, le nombre final de morceaux peut différer de la cible ; définir la cible près de la limite de 99 999 peut toujours déclencher l'erreur.

Problème 25 : ODPS-0110061:Échec de l'exécution de ddltask — ODPS-0130131:Table not found

Cette erreur apparaît dans les travaux MaxFrame de longue durée (plus de 24 heures). Une tâche interne de langage de définition de données (DDL) échoue car une table temporaire créée précédemment dans la session a expiré.

Les tables temporaires créées lors du calcul (par exemple, après un appel df.execute()) ont une durée de vie (TTL) par défaut d'un jour. Les tables de destination spécifiées avec to_odps_table ne sont pas concernées.

Augmentez la TTL des tables temporaires pour couvrir la durée prévue du travail :

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

Problème 26 : NoTaskServerResponseError

La session MaxFrame a expiré. Par défaut, une session expire après 1 heure d'inactivité. Si vous faites une pause dans un notebook Jupyter pendant plus d'une heure avant d'exécuter la cellule suivante, la session est perdue.

Si vous avez déjà rencontré cette erreur : Recréez la session. L'état de calcul des cellules précédentes n'est pas conservé.

Pour éviter cette erreur lors des prochaines exécutions : Étendez le délai d'inactivité avant de démarrer la session :

from maxframe import options

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

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

Cette erreur apparaît lors de l'impression d'un DataFrame contenant une colonne BIGINT ou INT avec des valeurs NULL ou INF — y compris l'affichage automatique dans une cellule de notebook Jupyter. Le problème sous-jacent est que pandas ne peut pas représenter NULL dans les colonnes entières ; les valeurs NULL sont stockées en interne sous forme de FLOAT, et leur conversion en entier échoue.

L'équipe MaxFrame travaille sur une correction à long terme. Pour l'instant, utilisez l'une de ces solutions de contournement :

1. Remplissez les valeurs NULL avant l'impression : df["col"].fillna(0)

2. Convertissez la colonne en float avant l'impression : df["col"].astype(float)

3. Évitez d'imprimer la colonne sauf si nécessaire.

Problème 28 : ODPS-0010000:Erreur interne du système — échec du travail fuxi, échec du travail SQL après trop de basculements

Les données de brassage sont trop volumineuses, ce qui entraîne un épuisement de la mémoire (OOM) du Job Master. Cela se produit généralement lorsqu'un travail avec des opérations Reduce ou Join génère trop d'instances de mappeur ou de réducteur/joineur.

Déclencheurs courants :

• Une valeur split.size très petite ou une valeur split.dop très grande qui crée trop d'instances de mappeur

• Une valeur reducer.num ou joiner.num importante qui crée trop d'instances de réducteur ou de joineur

Réduisez le nombre de mappeurs et de réducteurs/joineurs. Le total combiné ne doit pas dépasser 10 000. Si l'erreur persiste, contactez l'équipe MaxCompute.

Problème 29 : ODPS-0010000:Erreur interne du système — Total resource size must be <= 2048MB

Une UDF dépend de ressources dont la taille combinée dépasse la limite de 2 048 Mo.

Utilisez plutôt l'accélération du volume externe pour télécharger les ressources depuis Object Storage Service (OSS) au moment de l'exécution. Cette approche évite la contrainte de 2 048 Mo et offre des vitesses de téléchargement plus rapides.

Problème 30 : ODPS-0130071 : Exception d'analyse sémantique — column values_list in source has incompatible type ARRAY/MAP/STRUCT

Les données contiennent des tableaux, des maps ou des structs, et la déclaration de type ne correspond pas.

1. Mettez à niveau le client MaxFrame et réessayez : pip install -U maxframe.

2. Si l'erreur persiste, contactez l'équipe MaxFrame. Il peut s'agir d'un bogue dans le système de types MaxFrame.

Problème 31 : Sortie de brassage trop volumineuse

Utilisez l'indicateur odps.sql.sys.flag.fuxi_JobMaxInternalFolderSize pour spécifier l'espace de brassage maximal en Mo.