Execute o runtime do Copilot no mesmo processo

Quando usar 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 o Configuração padrão (CLI empacotada) quando o isolamento de processos e o caminho de implantação mais consolidado 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 utilizando o protocolo JSON-RPC existente (com enquadramento Content-Length) sobre 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 workers disponíveis durante todo o ciclo de vida do processo do 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 mecanismo de fallback para o usuário autenticado.
• 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 snapshot do ambiente host, além de substituições (overrides) suportadas e gerenciadas pelo SDK. 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. Encerre os clientes de forma adequada antes que o aplicativo seja finalizado.

Comportamento do ciclo de vida

Ao iniciar um cliente em processo, a biblioteca nativa é carregada, um host de tempo de runtime, uma conexão em memória é aberta e o handshake normal de protocolo e versão do SDK é realizado.

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 runtime.

A biblioteca nativa pode permanecer carregada até que o processo do aplicativo seja encerrado. Não dependa de descarregar e substituir a biblioteca de runtime 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