Installer, télécharger et prendre des décisions typées

Laya-CoreML tourne sur Apple Silicon avec macOS 15+ et Python 3.11–3.13. Les contrôles de release locaux utilisent M3 Max / macOS 27.2. Les versions macOS plus anciennes et le déploiement iOS n’ont pas été testés ici. Les ML Programs exportés ciblent macOS 15 / iOS 18.

python -m pip install laya-coreml
# Terminal demo and recording renderer:
python -m pip install 'laya-coreml[demo]'

L’inférence installe Core ML Tools, NumPy, Tokenizers, Safetensors et Hugging Face Hub. Elle ne nécessite ni PyTorch, ni Transformers, ni MLX. L’extra optionnel [convert] installe PyTorch pour exporter les checkpoints d’origine.

Sélectionner un modèle

Les paquets ANE incluent leurs propres poids d’embedding/action hôte et le corps Core ML inchangé. Ils n’ont pas besoin d’un répertoire de checkpoint d’origine. La capacité de 96 tokens inclut la question, les descriptions d’options, les marqueurs spéciaux et l’état. Ces exports courts rejettent une requête qui ne tient pas. Les modèles généralistes conservent la troncature d’état en amont à leur limite de contexte de checkpoint complète ; les descriptions d’options utilisent aussi le budget d’origine du préfixe de question.

API Python

import laya_coreml as laya

agent = laya.load("aac6fef/laya-multilingual-coreml")
result = agent.predict(
    "The customer asks for a refund of a duplicate payment.",
    {
        "department": {
            "type": "choice",
            "instructions": "Which department should handle this request?",
            "criteria": {
                "billing": "Payments, invoices, refunds, and duplicate charges.",
                "technical": "Broken features, errors, and product troubleshooting.",
                "sales": "Pricing, upgrades, and new purchases.",
            },
        },
        "urgency": {
            "type": "score",
            "instructions": "How urgent is the request?",
            "criteria": ["low", "medium", "high"],
        },
        "refund": {
            "type": "noul",
            "instructions": "Does the customer request a refund?",
        },
    },
)
print(result["answers"])
print(result["usage"])  # output_tokens is always 0

choice renvoie un libellé sélectionné et une probabilité pour chaque libellé. score renvoie l’index de catégorie attendu indexé à partir de zéro, sa légende et ses probabilités. noul renvoie la probabilité de vrai. Les réponses incluent aussi les champs de confiance en amont et de probabilité de tête d’action. Ces estimations peuvent être fausses ; la validation de la bibliothèque mesure la fidélité de conversion, pas l’exactitude applicative.

predict et system_one sont des alias. Un état sous forme de dictionnaire est sérialisé selon les conventions d’entrée d’origine. Les questions sont traitées dans l’ordre d’insertion. La plupart des exports utilisent un lot de un ; plusieurs questions nécessitent donc plusieurs appels au modèle. L’export Snake GPU met en lot jusqu’à trois. L’encodeur bidirectionnel ne met pas en cache l’état contextuel d’une question à l’autre.

Télécharger une fois, puis travailler hors ligne

hf download aac6fef/laya-multilingual-coreml-ane --local-dir models/ane

agent = laya.load("./models/ane", local_files_only=True)
# Or use a previously downloaded shared Hub cache:
agent = laya.load("aac6fef/laya-multilingual-coreml-ane", local_files_only=True)

Les ID distants se téléchargent avant l’initialisation, sauf avec local_files_only=True. Les prédictions suivantes n’utilisent que des tableaux et des fichiers locaux. Pour reproduire un instantané distant exact, passe revision="<Hub commit SHA>" ; les ID de commit de release sont dans RELEASE.md. Le jeu terminal utilise toujours des poids locaux/en cache et échoue avec une commande de téléchargement quand ils manquent.

Le cache partagé de Hugging Face stocke les fichiers de modèle sous forme de liens symboliques. Sur la version macOS testée, Core ML peut copier ces liens dans son modèle compilé temporaire et perdre le fichier de poids. Le loader matérialise automatiquement le paquet Core ML seul sous forme de fichiers réguliers dans ~/.cache/laya-coreml/packages/, vérifie son hash de contenu et réutilise cette copie. Définis LAYA_COREML_CACHE pour changer cette racine de cache. Cela utilise de l’espace disque supplémentaire, pas des téléchargements de modèle supplémentaires. Un répertoire créé avec hf download --local-dir contient déjà des fichiers réguliers et n’a besoin d’aucune copie.

Le loader reconnaît le format du paquet et sélectionne ses unités de calcul par défaut. Remplace avec compute_units="cpu_gpu", "cpu_ne", "cpu" ou "all" pour une expérience explicite. cpu_ne autorise le travail CPU et le travail ANE ; cela ne garantit pas que chaque opération s’exécute sur l’ANE. Le choisir pour l’export SDPA ordinaire ne transforme pas cet export en graphe ANE dédié.

CLI

Enregistre le dictionnaire de questions dans questions.json, puis lance :

laya-coreml predict ./models/ane --offline \
  --state 'The customer requests a refund.' --questions questions.json

laya-coreml predict accepte un répertoire local ou un ID Hub, un --revision optionnel et --compute-units. --offline empêche l’accès au Hub.

Convertir depuis les sources

Pour le chemin Core ML ordinaire :

pip install 'laya-coreml[convert]'
laya-coreml convert laya-multilingual models/custom-multilingual

L’exportateur de recherche ANE vit dans le checkout Git, en dehors de la wheel d’inférence :

git clone https://github.com/mizorewww/laya-coreml
cd laya-coreml
pip install -e '.[convert,dev,research]'
python -m experiments.ane_engineering.probe --source laya-multilingual \
  --kind body --length 96 --output models/ane96

Voir les conclusions de conversion, l’ingénierie ANE et les contrôles et l’enregistrement Snake pour les workflows correspondants.