Executar o runtime do Copilot em processo

Quando usar a hospedagem em processo

A hospedagem em processo é uma boa opção quando:

• Seu aplicativo deve ser executado sem um processo de runtime separado.
• Você quer que o SDK gerencie o ciclo de vida do runtime.
• Você pode enviar uma biblioteca nativa para cada plataforma de implantação.
• As configurações de ambiente e de diretório de trabalho de todo o processo são aceitáveis.

Use Configuração padrão (CLI empacotada) quando o isolamento do processo e o caminho de implantação mais estabelecido forem mais importantes. Use um Configuração de serviços de back-end quando várias instâncias de aplicativo precisarem se conectar a um runtime compartilhado via TCP.

Como funciona

O SDK carrega a biblioteca nativa do runtime do Copilot e faz a vinculação com sua ABI C fixa. Todos os métodos do SDK continuam usando o protocolo JSON-RPC existente, delimitado por Content-Length, por uma conexão em memória.

O tempo de execução:

• É executado no processo de aplicativo sem Node.js, um processo filho, uma porta TCP ou um token de conexão.
• Oferece suporte às mesmas sessões, eventos de streaming, ferramentas, ganchos, permissões e solicitações do servidor para o cliente, assim como outros transportes.
• Pode invocar callbacks do SDK a partir de threads de trabalho nativas. O SDK gerencia o encaminhamento entre threads e o ciclo de vida dos callbacks.
• Mantém a biblioteca nativa carregada e seu pool de trabalho disponíveis durante o tempo de vida do processo de aplicativo.

Requisitos do SDK

Todos os SDKs expõem uma opção de conexão explícita em processo. Algumas linguagens exigem configuração adicional de compilação ou de pacote.

O pacote de runtime nativo deve corresponder ao sistema operacional host, à arquitetura da CPU e à biblioteca C do Linux. Os hosts sem suporte falham durante a resolução ou inicialização em tempo de execução, em vez de retornar a um processo filho.

Configurar uma conexão em processo

Passe a opção de conexão específica do idioma ao criar o 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();
    }
}

Você também pode definir COPILOT_SDK_DEFAULT_CONNECTION=inprocess antes de iniciar o aplicativo. O SDK usa esse valor somente quando o cliente não especifica uma conexão explicitamente. Um valor inválido faz com que a inicialização falhe.

Prefira a configuração explícita do cliente no código do aplicativo. Use a variável de ambiente quando a configuração de implantação deve selecionar o transporte sem alterar o aplicativo.

Configurar o tempo de execução

O SDK converte opções tipadas de cliente compatíveis em argumentos nativos de runtime e valores de ambiente no escopo do host. Dependendo do SDK, essas opções incluem:

• Token de autenticação e fallback de usuário conectado.
• Diretório base do Copilot.
• Nível de log.
• Tempo limite de ociosidade da sessão.
• Modo de sessão remota.

O runtime em processo recebe um instantâneo do ambiente do host, além de substituições gerenciadas pelo SDK com suporte. Ele não modifica o ambiente do host.

Defina valores em todo o processo antes de criar o primeiro cliente em processo. Isso inclui variáveis de ambiente que não são representadas por opções de cliente tipadas e pelo diretório de trabalho atual do aplicativo.

Resolução da biblioteca em tempo de execução

Cada SDK procura primeiro uma biblioteca de runtime empacotada ou armazenada em cache compatível. Você pode configurar COPILOT_CLI_PATH para apontar para um pacote de runtime compatível do Copilot quando precisar fornecer o runtime separadamente.

Normalmente, apenas um caminho e uma versão da biblioteca nativa de tempo de execução podem ser carregados em um processo. Há suporte para iniciar outro cliente com a mesma biblioteca carregada, mas a tentativa de carregar uma biblioteca de runtime diferente falha.

Para implantações de produção:

1. Crie e teste o aplicativo para cada plataforma de destino.
2. Verifique se o artefato de runtime nativo correspondente está incluído no pacote implantado ou disponível por meio do mecanismo de download de runtime do SDK.
3. Inicie pelo menos uma sessão e conclua uma curva de modelo em um teste de fumaça de implantação.
4. Interrompa os clientes normalmente antes que o aplicativo seja encerrado.

Comportamento do ciclo de vida

Iniciar um cliente em processo carrega a biblioteca nativa, cria um host de runtime, abre uma conexão na memória e executa o handshake normal de versão de protocolo do SDK.

Durante o desligamento normal, o SDK:

1. Fecha sessões ativas.
2. Solicita o desligamento normal do ambiente de execução via JSON-RPC.
3. Fecha o JSON-RPC e as conexões nativas.
4. Libera o host de tempo de execução.

A biblioteca nativa pode permanecer carregada até que o processo do aplicativo seja encerrado. Não conte com descarregar e substituir a biblioteca de tempo de execução após o primeiro uso.

Limitations

A hospedagem em processo tem estas restrições atuais:

• API experimental: os requisitos de comportamento e empacotamento podem ser alterados entre versões.
• Estado do processo compartilhado: todos os clientes compartilham o ambiente do processo de host, o diretório de trabalho atual, a biblioteca nativa e o pool de trabalho de runtime.
• Opções de processo restrito: as opções do SDK para um ambiente arbitrário, diretório de trabalho, configuração de telemetria, caminho executável ou argumentos da CLI são rejeitadas quando aplicável. Configure valores globais do processo no processo hospedeiro e use opções tipadas compatíveis para configurações de tempo de execução.
• Nenhum diretório de trabalho por cliente: o runtime usa o diretório de trabalho do processo de hospedagem.
• Uma versão de runtime por processo: não há suporte para carregar outro caminho ou versão de biblioteca nativa.
• A maturidade da plataforma varia: algumas combinações de SDK e plataforma reduziram a cobertura de desligamento ou de turno de modelo. Valide a combinação exata que você implanta.

Leitura adicional

• Guias de configuração: comparar a hospedagem em processo com outros modelos de implantação
• Configuração padrão (CLI empacotada): execute o runtime empacotado em um processo filho gerenciado
• Configuração de serviços de back-end: conectar aplicativos a um runtime compartilhado via TCP
• Ganchos de ciclo de vida de sessão: manipular eventos de início e término da sessão