Ejecute el entorno de ejecución de Copilot en proceso

Cuándo usar el hospedaje en proceso

El hospedaje en proceso es una buena opción cuando:

• La aplicación debe ejecutarse sin un proceso en tiempo de ejecución independiente.
• Quieres que el SDK controle el ciclo de vida del entorno de ejecución.
• Puede enviar una biblioteca nativa para cada plataforma de implementación.
• El entorno de todo el proceso y la configuración del directorio de trabajo son aceptables.

Use el Configuración predeterminada (CLI agrupada) cuando el aislamiento de procesos y el método de implementación más consolidado sean más importantes. Use un Configuración de servicios back-end cuando varias instancias de aplicación deben conectarse a un entorno de ejecución compartido a través de TCP.

Cómo funciona

El SDK carga la biblioteca nativa del entorno de ejecución de Copilot y enlaza su ABI de C fija. Todos los métodos del SDK siguen utilizando el protocolo JSON-RPC existente enmarcado con Content-Length a través de una conexión en memoria.

El tiempo de ejecución:

• Se ejecuta en el proceso de aplicación sin Node.js, un proceso secundario, un puerto TCP o un token de conexión.
• Admite las mismas sesiones, eventos de streaming, herramientas, enlaces, permisos y solicitudes de servidor a cliente que otros transportes.
• Puede invocar funciones de devolución de llamada del SDK desde hilos de trabajo nativos. El SDK gestiona la transferencia entre hilos y el ciclo de vida de los callback.
• Mantiene la biblioteca nativa cargada y su grupo de trabajo disponible durante la vigencia del proceso de aplicación.

Requisitos del SDK

Todos los SDK exponen una opción de conexión explícita en proceso. Algunos lenguajes requieren configuración adicional de compilación o paquete.

El paquete nativo en tiempo de ejecución debe coincidir con el sistema operativo anfitrión, la arquitectura de la CPU y, en Linux, la biblioteca de C. Los hosts no admitidos producen un error durante la resolución o el inicio en tiempo de ejecución en lugar de revertir a un proceso secundario.

Configuración de una conexión en proceso

Pase la opción de conexión específica del idioma al crear el cliente.

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

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

await client.start();

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()

#pragma warning disable GHCP001

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

await client.StartAsync();

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

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

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();
    }
}

También puede establecer COPILOT_SDK_DEFAULT_CONNECTION=inprocess antes de iniciar la aplicación. El SDK usa este valor solo cuando el cliente no especifica explícitamente una conexión. Un valor no válido hace que se produzca un error de inicio.

Se prefiere la configuración de cliente explícita en el código de la aplicación. Use la variable de entorno cuando la configuración de implementación debe seleccionar el transporte sin cambiar la aplicación.

Configuración del entorno de ejecución

El SDK convierte las opciones tipadas de cliente compatibles en argumentos nativos del entorno de ejecución y valores de entorno del ámbito del host. En función del SDK, estas opciones incluyen:

• Token de autenticación y alternativa del usuario autenticado.
• Directorio base de Copilot.
• Nivel de registro.
• Tiempo de espera por inactividad de la sesión.
• Modo de sesión remota.

El entorno de ejecución en proceso recibe una instantánea del entorno del host junto con las anulaciones admitidas administradas por el SDK. No muta el entorno de host.

Establezca los valores de todo el proceso antes de crear el primer cliente en proceso. Esto incluye variables de entorno que no se representan mediante opciones tipadas del cliente y el directorio de trabajo actual de la aplicación.

Resolución de biblioteca en tiempo de ejecución

Cada SDK busca primero una biblioteca en tiempo de ejecución agrupada o almacenada en caché compatible. Puede establecer COPILOT_CLI_PATH para que apunte a un paquete de tiempo de ejecución de Copilot compatible cuando necesite proporcionar el tiempo de ejecución por separado.

Normalmente, en un proceso solo se puede cargar una única ruta de acceso y una única versión de la biblioteca nativa en tiempo de ejecución. Se admite iniciar otro cliente con la misma biblioteca cargada, pero se produce un error al intentar cargar otra biblioteca en tiempo de ejecución.

Para implementaciones de producción:

1. Compile y pruebe la aplicación para cada plataforma de destino.
2. Asegúrese de que el artefacto en tiempo de ejecución nativo coincidente se incluye en el paquete implementado o está disponible a través del mecanismo de descarga en tiempo de ejecución del SDK.
3. Inicie al menos una sesión y complete un turno del modelo en una prueba de humo del despliegue.
4. Detenga los clientes de forma ordenada antes de cerrar la aplicación.

Comportamiento del ciclo de vida

Al iniciar un cliente en proceso, se carga la biblioteca nativa, se crea un host en tiempo de ejecución, se abre una conexión en memoria y se realiza el protocolo de enlace normal de la versión del protocolo del SDK.

Durante el apagado controlado, el SDK:

1. Cierra las sesiones activas.
2. Solicita el apagado normal del tiempo de ejecución a través de JSON-RPC.
3. Cierra el JSON-RPC y las conexiones nativas.
4. Libera el host del entorno de ejecución.

La biblioteca nativa puede permanecer cargada hasta que se cierre el proceso de aplicación. No dependa de la descarga y sustitución de la biblioteca en tiempo de ejecución después del primer uso.

Limitations

El hospedaje en proceso tiene estas restricciones actuales:

• API experimental: los requisitos de comportamiento y empaquetado pueden cambiar entre versiones.
• Estado de proceso compartido: todos los clientes comparten el entorno de proceso de host, el directorio de trabajo actual, la biblioteca nativa y el grupo de trabajo en tiempo de ejecución.
• Opciones de proceso restringido: las opciones del SDK para un entorno arbitrario, el directorio de trabajo, la configuración de telemetría, la ruta de acceso ejecutable o los argumentos de la CLI se rechazan cuando corresponda. Configure los valores globales del proceso en el proceso host y use las opciones tipadas compatibles para la configuración del entorno de ejecución.
• No hay directorio de trabajo por cliente: el tiempo de ejecución usa el directorio de trabajo del proceso de hospedaje.
• Una versión en tiempo de ejecución por proceso: no se admite la carga de otra ruta de acceso o versión de biblioteca nativa.
• La madurez de la plataforma varía: algunas combinaciones de SDK y plataforma ofrecen una cobertura reducida de turnos de modelo o de apagado. Valide la combinación exacta que implemente.

Lectura adicional

• Guías de configuración: comparación del hospedaje en proceso con otros modelos de implementación
• Configuración predeterminada (CLI agrupada): ejecute el tiempo de ejecución agrupado en un proceso secundario administrado.
• Configuración de servicios back-end: conexión de aplicaciones a un entorno de ejecución compartido a través de TCP
• Enlaces de ciclo de vida de sesión: controlar los eventos de inicio y finalización de la sesión