Exécuter le runtime Copilot dans le processus

Avertissement

L’hébergement in-process est expérimental avec tous les SDK. Testez le démarrage, les cycles du modèle et le comportement à l’arrêt sur chaque système d’exploitation et chaque architecture que vous déployez.

Quand utiliser l’hébergement dans le processus

L’hébergement in-process est adapté quand :

Votre application doit s’exécuter sans processus d’exécution distinct.
Vous souhaitez que le Kit de développement logiciel (SDK) possède le cycle de vie du runtime.
Vous pouvez expédier une bibliothèque native pour chaque plateforme de déploiement.
Les paramètres d’environnement à l’échelle du processus et de répertoire de travail sont acceptables.

Utilisez l’AUTOTITLE lorsque l’isolation du processus et le chemin de déploiement le plus établi sont plus importants. Utilisez un Configuration des services principaux quand plusieurs instances d’application doivent se connecter à un runtime partagé via TCP.

Fonctionnement

Le SDK charge la bibliothèque native d’exécution de Copilot et assure la liaison avec son ABI C stable. Toutes les méthodes du SDK continuent d’utiliser le protocole JSON-RPC existant délimité par Content-Length via une connexion en mémoire.

Diagramme : Organigramme montrant le processus décrit.

L’environnement d’exécution :

S’exécute dans le processus d’application sans Node.js, un processus enfant, un port TCP ou un jeton de connexion.
Prend en charge les mêmes sessions, événements de streaming, outils, hooks, autorisations et demandes serveur à client que d’autres transports.
Peut appeler des rappels du Kit de développement logiciel (SDK) à partir de threads de travail natifs. Le Kit de développement logiciel (SDK) gère la durée de vie du marshaling et du rappel des threads.
Maintient la bibliothèque native chargée et son pool de threads de travail disponibles pendant toute la durée de vie du processus de l’application.

Configuration requise du kit de développement logiciel (SDK)

Tous les SDK proposent une option explicite de connexion dans le même processus. Certaines langues nécessitent une configuration de build ou de package supplémentaire.

SDK	Option de connexion	Exigence supplémentaire
TypeScript	`RuntimeConnection.forInProcess()`	Aucun lorsque le package inclut un bundle d’exécution compatible
Python	`RuntimeConnection.for_inprocess()`	Pré-téléchargement avec `python -m copilot download-runtime --in-process` quand le téléchargement du runtime n’est pas disponible au démarrage
Go	`copilot.InProcessConnection{}`	Générer avec `-tags copilot_inprocess`
.NET	`RuntimeConnection.ForInProcess()`	Autoriser le diagnostic de l’API `GHCP001` expérimentale
Rust	`Transport::InProcess`	Activer la `bundled-in-process` fonctionnalité Cargo
Java	`RuntimeConnection.forInProcess()`	Ajouter JNA, un classificateur d’environnement d’exécution pour la plateforme, ainsi que l’activation explicite de l’API expérimentale

Le bundle d’exécution natif doit correspondre au système d’exploitation hôte, à l’architecture du processeur et, sur Linux, bibliothèque C. Les hôtes non pris en charge échouent pendant la résolution ou le démarrage de l’exécution au lieu de revenir à un processus enfant.

Configurer une connexion dans le processus

Transmettez l’option de connexion spécifique à la langue lorsque vous créez le client.

Langages de code navigation

TypeScript

import { CopilotClient, RuntimeConnection } from "@github/copilot-sdk";

const client = new CopilotClient({
  connection: RuntimeConnection.forInProcess(),
});

await client.start();

Python

from copilot import CopilotClient, RuntimeConnection

client = CopilotClient(
    connection=RuntimeConnection.for_inprocess(),
)

await client.start()

client := copilot.NewClient(&copilot.ClientOptions{
    Connection: copilot.InProcessConnection{},
})

if err := client.Start(context.Background()); err != nil {
    log.Fatal(err)
}
defer client.Stop()

.NET

#pragma warning disable GHCP001

var client = new CopilotClient(new CopilotClientOptions
{
    Connection = RuntimeConnection.ForInProcess(),
});

await client.StartAsync();

Rust

let options = ClientOptions::default()
    .with_transport(Transport::InProcess);

let client = Client::start(options).await?;

Java

import com.github.copilot.AllowCopilotExperimental;

@AllowCopilotExperimental
public class Example {
    public void run() throws Exception {
        CopilotClientOptions options = new CopilotClientOptions()
            .setConnection(RuntimeConnection.forInProcess());

        CopilotClient client = new CopilotClient(options);
        client.start().join();
    }
}

RuntimeConnection.forInProcess() est @CopilotExperimental, de sorte que la classe ou la méthode consommatrice doit choisir avec @AllowCopilotExperimental (ou compiler avec -Acopilot.experimental.allowed=true). Consultez Utilisation d’API expérimentales.

Vous pouvez également définir COPILOT_SDK_DEFAULT_CONNECTION=inprocess avant de démarrer l’application. Le Kit de développement logiciel (SDK) utilise cette valeur uniquement lorsque le client ne spécifie pas explicitement de connexion. Une valeur non valide provoque l’échec du démarrage.

Préférez la configuration du client explicite dans le code d’application. Utilisez la variable d’environnement lorsque la configuration du déploiement doit sélectionner le transport sans modifier l’application.

Configurer le runtime

Le Kit de développement logiciel (SDK) convertit les options clientes typées prises en charge en arguments d’exécution natifs et en valeurs d’environnement délimitées par l’hôte. En fonction du Kit de développement logiciel (SDK), ces options sont les suivantes :

Jeton d’authentification et solution de repli pour l’utilisateur connecté.
Répertoire de base de Copilot.
Niveau de journalisation.
Délai d’inactivité de session.
Mode de session à distance.

Le runtime in-process reçoit un instantané de l’environnement hôte ainsi que les substitutions prises en charge et gérées par le SDK. Il ne mute pas l’environnement hôte.

Définissez les valeurs à l’échelle du processus avant de créer le premier client in-process. Cela inclut les variables d’environnement qui ne sont pas représentées par les options clientes typées et le répertoire de travail actuel de l’application.

Résolution de bibliothèque runtime

Chaque Kit de développement logiciel (SDK) recherche d’abord une bibliothèque d’exécution groupée ou mise en cache compatible. Vous pouvez définir COPILOT_CLI_PATH pour qu’il pointe vers un package de runtime Copilot compatible lorsque vous devez fournir le runtime séparément.

Un seul chemin d’accès et une version de bibliothèque runtime natifs peuvent normalement être chargés dans un processus. Le démarrage d’un autre client avec la même bibliothèque chargée est pris en charge, mais la tentative de chargement d’une autre bibliothèque d’exécution échoue.

Pour les déploiements de production :

Générez et testez l’application pour chaque plateforme cible.
Vérifiez que l’artefact d’exécution natif correspondant est inclus dans le package déployé ou disponible via le mécanisme de téléchargement du runtime du SDK.
Démarrez au moins une session et terminez un tour de modèle dans un test de fumée de déploiement.
Arrêtez les clients proprement avant que l’application ne se ferme.

Comportement du cycle de vie

Le lancement d’un client in-process charge la bibliothèque native, crée un hôte de runtime, ouvre une connexion en mémoire et effectue la négociation habituelle de version du protocole du SDK.

Pendant l’arrêt correct, le Kit de développement logiciel (SDK) :

Ferme les sessions actives.
Demande l’arrêt normal du runtime sur JSON-RPC.
Ferme les connexions JSON-RPC et natives.
Libère l’hôte d’exécution.

La bibliothèque native peut rester chargée jusqu’à ce que le processus d’application se termine. Ne dépendez pas du déchargement et du remplacement de la bibliothèque d’exécution après la première utilisation.

Limitations

L’hébergement in-process présente les contraintes actuelles suivantes :

API expérimentale : les exigences de comportement et d’empaquetage peuvent changer entre les versions.
État du processus partagé : tous les clients partagent l’environnement de processus hôte, le répertoire de travail actuel, la bibliothèque native et le pool de workers d’exécution.
Options de processus restreintes : les options du Kit de développement logiciel (SDK) pour un environnement arbitraire, un répertoire de travail, une configuration de télémétrie, un chemin d’accès exécutable ou des arguments CLI sont rejetées le cas échéant. Configurez les valeurs globales de processus sur le processus hôte et utilisez les options typées prises en charge pour les paramètres d’exécution.
Aucun répertoire de travail par client : le runtime utilise le répertoire de travail du processus d’hébergement.
Une version du runtime par processus : le chargement d’un autre chemin de bibliothèque natif ou version n’est pas pris en charge.
La maturité des plateformes varie : certaines combinaisons de SDK et de plateformes offrent une couverture plus limitée pour les tours de modèle ou l’arrêt. Validez la combinaison exacte que vous déployez.

Lectures complémentaires

Guides sur la configuration : comparer l’hébergement in-process avec d’autres modèles de déploiement
Configuration par défaut (interface CLI groupée) : exécutez le runtime groupé dans un processus enfant managé
Configuration des services principaux : connecter des applications à un runtime partagé via TCP
Hooks du cycle de vie de la session : gérer les événements de début et de fin de session

Dans cet article