프로세스에서 Copilot 런타임 실행

경고

In-process 호스팅은 모든 SDK에서 실험적입니다. 배포하는 모든 운영 체제 및 아키텍처에서 시작, 모델 회전 및 종료 동작을 테스트합니다.

In-Process 호스팅을 사용하는 경우

In-Process 호스팅은 다음과 같은 경우에 적합합니다.

애플리케이션은 별도의 런타임 프로세스 없이 실행해야 합니다.
SDK가 런타임 수명 주기를 관리하도록 합니다.
각 배포 플랫폼에 대한 네이티브 라이브러리를 제공할 수 있습니다.
프로세스 수준 환경 및 작업 디렉터리 설정이 허용됩니다.

프로세스 격리 및 가장 설정된 배포 경로가 더 중요한 경우 기본 설정(번들 CLI) 을 사용합니다. 여러 애플리케이션 인스턴스가 TCP를 통해 공유 런타임에 연결해야 하는 경우 백 엔드 서비스 설정 을 사용합니다.

작동 방식

SDK는 Copilot 런타임 네이티브 라이브러리를 로드하고 고정 C ABI를 바인딩합니다. 모든 SDK 메서드는 메모리 내 연결을 통해 기존 Content-Length프레임 JSON-RPC 프로토콜을 계속 사용합니다.

다이어그램: 설명된 프로세스를 보여 주는 순서도입니다.

런타임:

Node.js, 자식 프로세스, TCP 포트 또는 연결 토큰 없이 애플리케이션 프로세스에서 실행됩니다.
다른 전송과 동일한 세션, 스트리밍 이벤트, 도구, 후크, 권한 및 서버-클라이언트 요청을 지원합니다.
네이티브 작업자 스레드에서 SDK 콜백을 호출할 수 있습니다. SDK는 스레드 마샬링 및 콜백 수명을 처리합니다.
로드된 네이티브 라이브러리와 해당 작업자 풀을 애플리케이션 프로세스의 수명 동안 사용할 수 있도록 유지합니다.

SDK 요구 사항

모든 SDK는 명시적 프로세스 내 연결 옵션을 노출합니다. 일부 언어에는 추가 빌드 또는 패키지 구성이 필요합니다.

SDK	연결 옵션	추가 요구 사항
TypeScript	`RuntimeConnection.forInProcess()`	패키지에 호환되는 런타임 번들이 포함된 경우 없음
Python	`RuntimeConnection.for_inprocess()`	시작 시 런타임 다운로드를 사용할 수 없는 경우 `python -m copilot download-runtime --in-process`로 사전 다운로드
Go	`copilot.InProcessConnection{}`
`-tags copilot_inprocess`로 빌드
.NET	`RuntimeConnection.ForInProcess()`	실험적 `GHCP001` API 진단 허용
러스트	`Transport::InProcess`
`bundled-in-process` Cargo 기능을 활성화
Java	`RuntimeConnection.forInProcess()`	JNA, 플랫폼 런타임 분류기 및 실험적 API 사용 설정 추가

네이티브 런타임 번들은 호스트 운영 체제, CPU 아키텍처 및 Linux의 C 라이브러리와 일치해야 합니다. 지원되지 않는 호스트는 자식 프로세스로 되돌아가는 대신 런타임 확인 또는 시작 중에 실패합니다.

프로세스 내 연결 구성

클라이언트를 만들 때 언어별 연결 옵션을 전달합니다.

코드 언어 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()는 @CopilotExperimental이므로 이를 사용하는 클래스 또는 메서드는 @AllowCopilotExperimental로 옵트인해야 합니다(또는 -Acopilot.experimental.allowed=true로 컴파일해야 합니다). 실험적 API 사용을 참조하세요.

애플리케이션을 시작하기 전에 COPILOT_SDK_DEFAULT_CONNECTION=inprocess을 설정할 수도 있습니다. SDK는 클라이언트가 연결을 명시적으로 지정하지 않는 경우에만 이 값을 사용합니다. 잘못된 값으로 인해 시작이 실패합니다.

애플리케이션 코드에서 명시적 클라이언트 구성을 선호합니다. 배포 구성이 애플리케이션을 변경하지 않고 전송을 선택해야 하는 경우 환경 변수를 사용합니다.

런타임 구성

SDK는 지원되는 형식화된 클라이언트 옵션을 네이티브 런타임 인수 및 호스트 범위 환경 값으로 변환합니다. SDK에 따라 이러한 옵션은 다음과 같습니다.

인증 토큰 및 로그인 사용자 대체 처리
Copilot 기본 디렉터리입니다.
로그 수준.
세션 유휴 시간 초과
원격 세션 모드입니다.

In-process 런타임은 호스트 환경의 스냅샷과 지원되는 SDK 관리 재정의를 받습니다. 호스트 환경은 변경되지 않습니다.

첫 번째 In-Process 클라이언트를 만들기 전에 프로세스 수준 값을 설정합니다. 여기에는 형식화된 클라이언트 옵션 및 애플리케이션의 현재 작업 디렉터리로 표현되지 않는 환경 변수가 포함됩니다.

런타임 라이브러리 해결

각 SDK는 먼저 호환되는 번들 또는 캐시된 런타임 라이브러리를 찾습니다. 런타임을 별도로 제공해야 하는 경우 호환되는 Copilot 런타임 패키지를 가리키도록 설정할 COPILOT_CLI_PATH 수 있습니다.

하나의 네이티브 런타임 라이브러리 경로 및 버전만 일반적으로 프로세스에서 로드할 수 있습니다. 동일한 로드된 라이브러리를 사용하여 다른 클라이언트를 시작하는 것은 지원되지만 다른 런타임 라이브러리를 로드하려고 시도하면 실패합니다.

프로덕션 배포의 경우:

각 대상 플랫폼에 대한 애플리케이션을 빌드하고 테스트합니다.
일치하는 네이티브 런타임 아티팩트가 배포된 패키지에 포함되거나 SDK의 런타임 다운로드 메커니즘을 통해 사용할 수 있는지 확인합니다.
하나 이상의 세션을 시작한 후 배포 스모크 테스트에서 모델 턴 1회를 완료하세요.
애플리케이션이 종료되기 전에 클라이언트를 정상적으로 중지합니다.

수명 주기 동작

In-process 클라이언트를 시작하면 네이티브 라이브러리를 로드하고, 런타임 호스트를 만들고, 메모리 내 연결을 열고, 일반 SDK 프로토콜 버전 핸드셰이크를 수행합니다.

정상적으로 종료하는 동안 SDK는 다음을 수행합니다.

활성 세션을 닫습니다.
JSON-RPC를 통해 정상적인 런타임 종료를 요청합니다.
JSON-RPC 및 네이티브 연결을 닫습니다.
런타임 호스트를 해제합니다.

네이티브 라이브러리는 애플리케이션 프로세스가 종료될 때까지 로드된 상태를 유지할 수 있습니다. 처음 사용한 후 런타임 라이브러리를 언로드하고 바꾸는 데 의존하지 마세요.

Limitations

In-Process 호스팅에는 다음과 같은 현재 제약 조건이 있습니다.

실험적 API: 동작 및 패키징 요구 사항은 릴리스 간에 변경될 수 있습니다.
공유 프로세스 상태: 모든 클라이언트는 호스트 프로세스 환경, 현재 작업 디렉터리, 네이티브 라이브러리 및 런타임 작업자 풀을 공유합니다.
제한된 프로세스 옵션: 임의 환경, 작업 디렉터리, 원격 분석 구성, 실행 경로 또는 CLI 인수에 대한 SDK 옵션은 해당하는 경우 거부됩니다. 호스트 프로세스에서 프로세스-전역 값을 구성하고 런타임 설정에 지원되는 형식화된 옵션을 사용합니다.
클라이언트별 작업 디렉터리 없음: 런타임은 호스팅 프로세스 작업 디렉터리를 사용합니다.
프로세스당 하나의 런타임 버전: 다른 네이티브 라이브러리 경로 또는 버전을 로드하는 것은 지원되지 않습니다.
플랫폼 완성도는 다양합니다. 일부 SDK 및 플랫폼 조합은 모델 턴 또는 종료 범위를 줄입니다. 배포하는 정확한 조합의 유효성을 검사합니다.

추가 읽기

설정 가이드: In-Process 호스팅을 다른 배포 모델과 비교
기본 설정(번들 CLI): 관리되는 자식 프로세스에서 번들 런타임 실행
백 엔드 서비스 설정: TCP를 통해 애플리케이션을 공유 런타임에 연결
세션 수명 주기 후크: 세션 시작 및 종료 이벤트 처리

이 기사에서