Documentazione di CapDAG

Costruire ed eseguire una cartuccia

Un tutorial che porta una cartuccia attraverso il ciclo di sviluppo locale: scheletro, build, installazione, esecuzione, modifica e reinstallazione.

In questa sezione

Questo tutorial porta una cartuccia attraverso il ciclo di sviluppo locale: creazione dello scheletro, build quando serve, installazione, esecuzione, modifica e reinstallazione. Il sentiment-tagger generato possiede una piccola capacità di dominio e delega la classificazione vera e propria alla capacità pubblicata classify-en.

Prerequisiti

Ti servono:

  • la CLI capdag nel PATH;
  • la toolchain del linguaggio che scegli;
  • una cartuccia di modello installata localmente che fornisca classify-en; e
  • l’accesso alla rete alla prima esecuzione del modello, se quella cartuccia deve scaricare il proprio modello.

Per Python, installa Python 3.11 o successivo e il runtime della cartuccia:

python3 -m pip install capdag

Il punto di ingresso Python generato usa #!/usr/bin/env python3. Il python3 trovato nel PATH deve quindi essere in grado di importare capdag.

1. Crea il progetto {#1-create-the-project}

capdag new sentiment-tagger --python
cd sentiment-tagger

--rust, --go e --swift producono progetti equivalenti per i runtime di cartuccia di quei linguaggi. Il README generato riporta il comando di build specifico del linguaggio.

Il progetto Python contiene:

sentiment-tagger/
  cartridge.py
  README.md
  .gitignore

Il punto di ingresso generato:

  1. Definisce i media URN di input e di output specifici del progetto.
  2. Costruisce un cap URN personalizzato e lo annuncia insieme alla cap di identità obbligatoria.
  3. Registra un handler TagOp per la stringa canonica del cap URN.
  4. Chiama classify-en con il testo di input e l’insieme chiuso di etichette positive,neutral,negative.
  5. Inoltra l’avanzamento del peer ed emette l’etichetta restituita.

I media URN generati includono il nome del progetto, così una cap di sviluppo non pubblicata non riutilizza per errore un tipo pubblicato:

media:enc=utf-8;sentiment-tagger-input
media:enc=utf-8;sentiment-tagger-tag

La capacità personalizzata ha la forma canonica:

cap:in="media:enc=utf-8;sentiment-tagger-input";out="media:enc=utf-8;sentiment-tagger-tag";sentiment-tagger

Tratta i tagged URN come valori opachi. Lo scheletro costruisce il cap URN con CapUrnBuilder e riutilizza la sua stringa canonica per la registrazione; non ricostruire quella stringa nel codice dell’handler.

Esamina il manifest prima dell’installazione:

./cartridge.py manifest | python3 -m json.tool

Per un linguaggio compilato, esegui prima il suo comando di build ed esamina invece il sottocomando manifest dell’eseguibile generato.

2. Installa la cartuccia di sviluppo {#2-install-the-development-cartridge}

capdag dev-install .

Per Rust, Go e Swift, compila l’eseguibile generato prima di questo comando. dev-install legge il manifest, confronta i suoi alias con il fabric e colloca il progetto in:

~/.capdag/cartridges/dev/v{registry-version}/nightly/sentiment-tagger/0.1.0/

Lo slug dev è riservato ai manifest il cui registry_url è null. Reinstallare la stessa versione sostituisce quell’installazione di sviluppo.

Una cap di sviluppo può introdurre un alias assente dal fabric. Non può rivendicare un alias che il fabric associa già a una capacità diversa. Rinomina un alias in conflitto prima di continuare.

3. Esegui la capacità {#3-run-the-capability}

echo "I love this" | capdag sentiment-tagger

Esegui il punto di ingresso attraverso l’host capdag. Invocarlo direttamente non può soddisfare la sua chiamata peer e fallisce con Peer invocation not supported in this context.

In caso di successo, lo stdout contiene una delle tre etichette. L’avanzamento del download del modello e dell’inferenza compare attraverso il normale canale dell’avanzamento. Se nessuna cartuccia installata fornisce classify-en, la chiamata peer fallisce; lo scheletro non ha alcun classificatore di ripiego.

4. Modificala e reinstallala {#4-change-and-reinstall-it}

Apri il sorgente generato e cambia l’insieme delle etichette, i metadati della capacità o la capacità peer. Poi ricompila se necessario e reinstalla:

capdag dev-install .
echo "I love this" | capdag sentiment-tagger

Questo è il ciclo di sviluppo: modifica, build quando richiesta, dev-install ed esecuzione. Incrementa la versione del manifest per installare una nuova versione accanto a quella vecchia; altrimenti dev-install aggiorna la directory della versione corrente.

Aggiungere un’altra capacità

Ogni capacità aggiuntiva richiede:

  1. una Cap nel manifest, con tag di media e di operazione distinti;
  2. un’implementazione di Op; e
  3. una registrazione che usi esattamente la stringa canonica del cap URN annunciata dal manifest.

Il runtime crea l’handler registrato per ogni richiesta ed esegue il dispatch in base al cap URN della richiesta.

Pubblicare la cartuccia

Le definizioni locali diventano definizioni del registro quando la capacità è pronta per altri utenti. Proponi i nuovi cap URN e media URN a capfab, e proponi la cartuccia a cartridge-shelf. Un manifest pubblicato usa l’URL del proprio registro e viene installato sotto lo slug di quel registro invece che sotto dev.

Risolvere i problemi del ciclo di sviluppo

  • Conflitto di alias: rinomina un alias che il fabric assegna già a un cap URN diverso.
  • Nessun fornitore locale: esegui di nuovo capdag dev-install . e verifica che l’alias corrisponda al manifest.
  • Il comando manifest fallisce: rendi eseguibile il punto di ingresso e assicurati che le sue dipendenze di runtime siano disponibili all’interprete o all’eseguibile.
  • NoHandlerError: costruisci il cap URN una sola volta e usa la stessa stringa canonica sia nel manifest sia nella registrazione dell’handler.
  • L’invocazione peer fallisce: installa una cartuccia di modello compatibile che fornisca classify-en, poi esegui la cap di sviluppo attraverso l’host anziché direttamente dal suo punto di ingresso.

Vedi il riferimento della CLI di CapDAG per i dettagli sui comandi e sulle opzioni.