在进程中运行Copilot运行时

何时使用进程内托管

进程内托管适用于以下情况：

• 应用程序必须在没有单独的运行时进程中运行。
• 你希望 SDK 拥有运行时生命周期。
• 可以为每个部署平台提供一个原生库。
• 进程范围的环境和工作目录设置是可接受的。

当进程隔离和最建立的部署路径更重要时，请使用 默认设置（随附的 CLI） 。 当多个应用程序实例必须通过 TCP 连接到共享运行时时，请使用 后端服务设置 。

工作原理

SDK 加载 Copilot 运行时原生库，并绑定其固定 C ABI。 所有 SDK 方法继续通过内存中连接使用现有的 Content-Length框架 JSON-RPC 协议。

运行时：

• 在应用程序进程中运行，而无需 Node.js、子进程、TCP 端口或连接令牌。
• 支持与其他传输方式相同的会话、流式事件、工具、钩子、权限以及服务器到客户端的请求。
• 可以从原生工作线程调用 SDK 回调。 SDK 负责处理线程间调度和回调的生命周期。
• 使已加载的原生库及其工作线程池在整个应用程序进程生命周期内保持可用。

SDK 要求

所有 SDK 都公开显式进程内连接选项。 某些语言需要额外的构建或软件包配置。

原生运行时捆绑包必须与主机操作系统、CPU 架构以及在 Linux 上所使用的 C 库相匹配。 不支持的主机在运行时解析或启动期间失败，而不是回退到子进程。

配置进程内连接

创建客户端时传递特定于语言的连接选项。

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

还可以在启动应用程序之前进行设置 COPILOT_SDK_DEFAULT_CONNECTION=inprocess 。 仅当客户端未显式指定连接时，SDK 才使用此值。 无效值会导致启动失败。

首选应用程序代码中的显式客户端配置。 部署配置必须选择传输而不更改应用程序时，请使用环境变量。

配置运行时

SDK 将支持的类型化客户端选项转换为本机运行时参数和主机范围的环境值。 根据 SDK，这些选项包括：

• 身份验证令牌和已登录用户后备机制。
• Copilot 基础目录。
• 日志级别。
• 会话空闲超时。
• 远程会话模式。

进程内运行时接收主机环境的快照以及受支持的由 SDK 管理的覆盖项。 它不会改变主机环境。

在创建第一个进程内客户端之前设置进程范围值。 这包括未由类型化客户端选项和应用程序的当前工作目录表示的环境变量。

运行时库解析

每个 SDK 首先查找兼容的捆绑或缓存运行时库。 如果需要单独提供该运行时，可以将 COPILOT_CLI_PATH 设置为指向兼容的 Copilot 运行时包。

一个进程通常只能加载一个本机运行时库路径和版本。 支持启动具有相同加载库的另一个客户端，但尝试加载其他运行时库失败。

对于生产部署：

1. 为每个目标平台生成和测试应用程序。
2. 确保已部署的包中包含匹配的本机运行时项目，或通过 SDK 的运行时下载机制提供。
3. 至少启动一个会话，并在部署冒烟测试中完成一次模型轮次。
4. 在应用程序退出之前，请正常停止客户端。

生命周期行为

启动一个进程内客户端会加载原生库，创建运行时主机，打开一个内存中连接，并执行标准的 SDK 协议版本握手。

在正常关闭期间，SDK：

1. 关闭当前活动会话。
2. 请求通过 JSON-RPC 正常关闭运行时。
3. 关闭 JSON-RPC 和原生连接。
4. 释放运行时主机。

在应用程序进程退出之前，本机库可以保持加载状态。 不要依赖于首次使用后卸载和替换运行时库。

Limitations

进程内托管具有以下当前约束：

• 实验 API：行为和打包要求可以在版本之间更改。
• 共享进程状态：所有客户端共享主机进程环境、当前工作目录、本机库和运行时辅助角色池。
• 受限的进程选项：任意环境的 SDK 选项、工作目录、遥测配置、可执行路径或 CLI 参数在适用的情况下被拒绝。 在主机进程中配置进程全局值，并为运行时设置使用支持的类型化选项。
• 无每客户端工作目录：运行时使用托管进程工作目录。
• 每个进程的一个运行时版本：不支持加载另一个本机库路径或版本。
• 平台成熟度各不相同：某些 SDK 和平台组合对模型轮次或关停的支持覆盖较少。 验证您所部署的具体组合。

延伸阅读

• 安装指南：将进程内托管与其他部署模型进行比较
• 默认设置（随附的 CLI）：在受管理的子进程中运行随附的运行时
• 后端服务设置：通过 TCP 将应用程序连接到共享运行时
• 会话生命周期挂钩：处理会话启动和结束事件