Modalità TCP

Descrive come connetterti a un server Copilot CLI pre-avviato con Laravel Copilot SDK e usarlo in condivisione con basso overhead.

​

Modalità TCP

Di norma l’SDK avvia un nuovo processo Copilot CLI per ogni richiesta (modalità stdio). Con la modalità TCP puoi connetterti a un server Copilot CLI avviato in anticipo.

​

Vantaggi della modalità TCP

• Miglioramento delle performance: nessun overhead di avvio processo
• Condivisione delle risorse: più processi Laravel possono condividere lo stesso server CLI
• Gestione del processo: gestibile come processo in background con Laravel Forge / Laravel Cloud
• Adatto al deploy: supporta il riavvio automatico durante il deploy

​

Uso

​

1. Avvia il server Copilot CLI

copilot --headless --port 12345

​

2. Imposta la variabile d’ambiente

COPILOT_URL=tcp://127.0.0.1:12345
# COPILOT_URL=http://127.0.0.1:12345
# COPILOT_URL=127.0.0.1:12345
# COPILOT_URL=12345
# COPILOT_URL=127.0.0.1
# COPILOT_URL=localhost

Con questo, l’SDK passa automaticamente da stdio a TCP.

• tcp:// è opzionale. Funziona anche con http:// o senza schema.
• Puoi specificare solo la porta. In tal caso l’host è automaticamente 127.0.0.1.
• La specifica del solo host è valida solo per 127.0.0.1 e localhost. In tal caso la porta di default è 12345.

​

File di configurazione

Puoi configurare la connessione TCP in config/copilot.php.

return [
    // URL di destinazione TCP (se impostato attiva la modalità TCP)
    'url' => env('COPILOT_URL'),

    // I successivi vengono usati solo in modalità stdio
    'cli_path' => env('COPILOT_CLI_PATH', 'copilot'),
    'cli_args' => [],
    'cwd' => null,
    'log_level' => env('COPILOT_LOG_LEVEL', 'info'),

    // Comune a entrambe le modalità
    'timeout' => env('COPILOT_TIMEOUT', 60),
    'model' => env('COPILOT_MODEL'),
];

Se imposti sia COPILOT_URL (cli_url) sia COPILOT_CLI_PATH, ha priorità la modalità TCP.

​

Cambio di modalità a runtime

Di norma la modalità TCP o stdio viene scelta automaticamente in base al file di configurazione. Puoi anche cambiarla esplicitamente nel codice.

use Revolution\Copilot\Facades\Copilot;

// Passa alla modalità TCP
$response = Copilot::useTcp(url: 'tcp://127.0.0.1:12345')->run(prompt: 'Hello, TCP mode!');
// Se omessa, usa il valore del file di configurazione
$response = Copilot::useTcp()->run(prompt: 'Hello, TCP mode!');

// Passa alla modalità stdio
$stdioConfig = [
    'cli_path' => 'copilot',
    'cli_args' => [],
    'cwd' => base_path(),
    'log_level' => 'info',
];
$response = Copilot::useStdio($stdioConfig)->run(prompt: 'Hello, stdio mode!');

// Se omesso, usa il valore del file di configurazione
// Se sono impostate entrambe le modalità ha priorità TCP, quindi è utile per un override temporaneo
$response = Copilot::useStdio()->run(prompt: 'Hello, stdio mode!');

Con alcuni server la modalità TCP potrebbe non funzionare correttamente. È anche possibile alternare: modalità TCP per le queue, modalità stdio all’interno delle richieste HTTP.

​

Uso con Laravel Forge / Laravel Cloud

​

Laravel Forge

1. Crea un Daemon: crea un Daemon dalla dashboard Forge.

   Command: copilot --headless --port 12345
   User: forge
   Directory: /home/forge/your-app
   

2. Imposta la variabile d’ambiente: aggiungi COPILOT_URL in .env.

3. Riavvio al deploy: riavvia il Daemon nello script di deploy.

Con l’attuale ambiente Forge potrebbe non essere necessario.

sudo supervisorctl restart daemon-123456:*

​

Laravel Cloud

Puoi eseguirlo come processo in background usando la funzionalità worker di Laravel Cloud.

Per i dettagli consulta Uso su Laravel Cloud.

​

Note

​

Sicurezza

Usa per quanto possibile il bind locale (127.0.0.1) per il server TCP. Se lo esponi pubblicamente, configura in modo appropriato il firewall.

​

Riconnessione

La versione attuale non ha una riconnessione automatica. Se la connessione cade viene sollevata un’eccezione.

​

Verifica della modalità corrente

Nel codice puoi verificare in che modalità è il client.

use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

if ($client->isTcpMode()) {
    // modalità TCP
} else {
    // modalità stdio
}

​

Troubleshooting

​

Connessione fallita

1. Verifica che il server Copilot CLI sia in esecuzione

ps aux | grep copilot

2. Verifica che la porta sia corretta

netstat -an | grep 12345

3. Verifica la configurazione del firewall

​

Errore di timeout

Aumenta il valore di timeout in config/copilot.php.

'timeout' => 120, // 2 minuti

Per le informazioni più recenti fai riferimento al repository GitHub.