설치, 다운로드, 타입 지정 의사결정

Laya-CoreML은 macOS 15+와 Python 3.11–3.13을 갖춘 Apple Silicon에서 실행됩니다. 로컬 릴리스 검사는 M3 Max / macOS 27.2를 사용합니다. 이전 macOS 릴리스와 iOS 배포는 여기서 시험하지 않았습니다. 내보낸 ML Program은 macOS 15 / iOS 18을 대상으로 합니다.

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

추론은 Core ML Tools, NumPy, Tokenizers, Safetensors, Hugging Face Hub를 설치합니다. PyTorch, Transformers, MLX는 필요하지 않습니다. 선택적 [convert] extra는 원래 체크포인트를 내보내기 위한 PyTorch를 설치합니다.

모델 선택

ANE 패키지는 자체 호스트 임베딩/액션 가중치와 변경되지 않은 Core ML 본체를 포함합니다. 원래 체크포인트 디렉터리가 필요하지 않습니다. 96토큰 용량은 질문, 옵션 설명, 특수 마커, 상태를 포함합니다. 이 짧은 내보내기는 맞지 않는 요청을 거부합니다. 범용 모델은 전체 체크포인트 컨텍스트 한도에서 업스트림 상태 자르기를 유지하며, 옵션 설명도 원래 질문 프리픽스 예산을 사용합니다.

Python API

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는 선택된 레이블과 모든 레이블의 확률을 돌려줍니다. score는 0 기준 기대 범주 인덱스, 그 범례, 확률을 돌려줍니다. noul은 참일 확률을 돌려줍니다. 답에는 업스트림 신뢰도와 액션 헤드 확률 필드도 포함됩니다. 이 추정치는 틀릴 수 있으며, 라이브러리의 검증은 변환 충실도를 측정할 뿐 애플리케이션 정확도를 측정하지 않습니다.

predict와 system_one은 별칭입니다. 딕셔너리 상태는 원래 입력 규칙으로 직렬화됩니다. 질문은 삽입 순서로 처리됩니다. 대부분의 내보내기는 배치 1을 사용하므로, 여러 질문에는 여러 모델 호출이 필요합니다. Snake GPU 내보내기는 최대 세 개를 배치 처리합니다. 양방향 인코더는 서로 다른 질문에 걸쳐 문맥 상태를 캐시하지 않습니다.

한 번 다운로드하고 오프라인으로 작업하기

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)

원격 ID는 local_files_only=True가 아니면 초기화 전에 다운로드합니다. 이후 예측은 로컬 배열과 파일만 사용합니다. 정확한 원격 스냅샷을 재현하려면 revision="<Hub commit SHA>"를 전달하십시오. 릴리스 커밋 ID는 RELEASE.md에 있습니다. 터미널 게임은 항상 로컬/캐시된 가중치를 사용하며, 그것이 없으면 다운로드 명령과 함께 실패합니다.

Hugging Face의 공유 캐시는 모델 파일을 심볼릭 링크로 저장합니다. 시험한 macOS 릴리스에서 Core ML은 그 링크를 임시 컴파일 모델로 복사하면서 가중치 파일을 잃을 수 있습니다. 로더는 Core ML 패키지만 ~/.cache/laya-coreml/packages/ 아래의 일반 파일로 자동 구체화하고, 콘텐츠 해시를 검증하고, 그 복사본을 재사용합니다. 이 캐시 루트를 바꾸려면 LAYA_COREML_CACHE를 설정하십시오. 이는 추가 디스크 공간을 쓰지만 추가 모델 다운로드는 아닙니다. hf download --local-dir로 만든 디렉터리는 이미 일반 파일을 담고 있어 복사가 필요하지 않습니다.

로더는 패키지 형식을 인식하고 기본 컴퓨트 유닛을 선택합니다. 명시적 실험에는 compute_units="cpu_gpu", "cpu_ne", "cpu", "all" 중 하나로 재정의하십시오. cpu_ne는 CPU 작업과 ANE 작업을 허용하며, 모든 연산이 ANE에서 실행됨을 보장하지는 않습니다. 일반 SDPA 내보내기에 그것을 골라도 그 내보내기가 전용 ANE 그래프로 바뀌지는 않습니다.

CLI

질문 딕셔너리를 questions.json에 저장한 뒤 실행하십시오.

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

laya-coreml predict는 로컬 디렉터리 또는 Hub ID, 선택적 --revision, --compute-units를 받습니다. --offline은 Hub 접근을 막습니다.

소스에서 변환

일반 Core ML 경로:

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

ANE 연구 내보내기는 추론 휠 밖의 Git 체크아웃에 있습니다.

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

해당 워크플로는 변환 결과, ANE 엔지니어링, Snake 조작과 녹화를 참조하십시오.