使用图像输入的 Copilot SDK - GitHub 文档

注意

Copilot SDK 目前处于公开预览阶段。功能和可用性可能会更改。

有两种方式将图像附加到 Copilot SDK 会话

文件附件 (type: "file")—提供绝对路径；运行时从磁盘读取文件，转换为 base64，并发送给 LLM。
Blob 附件 (type: "blob")—直接提供 base64 编码的数据；当图像已在内存中时很有用（例如截图、生成的图像或 API 返回的数据）。

有关图像输入流程的序列图，请参阅 github/copilot-sdk 仓库。

概念	描述
文件附件	具有 `type: "file"` 且指向磁盘上图像的绝对 `path` 的附件
Blob 附件	具有 `type: "blob"`、base64 编码的 `data` 和 `mimeType` 的附件——无需磁盘 I/O
自动编码	对于文件附件，运行时会自动读取图像并转换为 base64
自动调整大小	运行时会自动调整或降低质量以处理超出模型特定限制的图像
视觉能力	模型必须具备 `capabilities.supports.vision = true` 才能处理图像

快速入门：文件附件

使用文件附件类型将图像文件附加到任何消息。路径必须是指向磁盘上图像的绝对路径。

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

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approved" }),
});

await session.send({
    prompt: "Describe what you see in this image",
    attachments: [
        {
            type: "file",
            path: "/absolute/path/to/screenshot.png",
        },
    ],
});

有关 Python、Go 和 .NET 示例，请参阅 github/copilot-sdk 仓库。对于 Java，请参阅 github/copilot-sdk-java 仓库。

快速入门：blob 附件

当你已经在内存中拥有图像数据（例如由应用捕获的截图，或从 API 获取的图像）时，使用 blob 附件直接发送，无需写入磁盘。

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

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approved" }),
});

const base64ImageData = "..."; // your base64-encoded image
await session.send({
    prompt: "Describe what you see in this image",
    attachments: [
        {
            type: "blob",
            data: base64ImageData,
            mimeType: "image/png",
            displayName: "screenshot.png",
        },
    ],
});

有关 Python、Go 和 .NET 示例，请参阅 github/copilot-sdk 仓库。对于 Java，请参阅 github/copilot-sdk-java 仓库。

支持的格式

支持的图像格式包括 JPG、PNG、GIF 等常见图像类型。对于文件附件，运行时会从磁盘读取图像并根据需要进行转换。对于 blob 附件，则直接提供 base64 数据和 MIME 类型。建议使用 PNG 或 JPEG，以获得最佳效果，因为它们是最广泛支持的格式。

模型的 capabilities.limits.vision.supported_media_types 字段列出了它接受的具体 MIME 类型。

自动处理

运行时会自动处理图像，以符合模型的限制。无需手动调整大小。

超出模型尺寸或大小限制的图像会自动调整大小（保持宽高比）或降低质量。
如果在处理后仍无法符合限制，该图像将被跳过，不会发送给 LLM。
模型的 capabilities.limits.vision.max_prompt_image_size 字段指示最大图像字节大小。

视觉模型能力

并非所有模型都支持视觉。发送图像前请检查模型的能力。

能力字段

字段	类型	描述
`capabilities.supports.vision`	`boolean`	模型是否能处理图像输入
`capabilities.limits.vision.supported_media_types`	`string[]`	模型接受的 MIME 类型（例如 `["image/png", "image/jpeg"]`）
`capabilities.limits.vision.max_prompt_images`	`number`	每个提示可包含的最大图像数量
`capabilities.limits.vision.max_prompt_image_size`	`number`	图像的最大字节大小

视觉限制类型

vision?: {
    supported_media_types: string[];
    max_prompt_images: number;
    max_prompt_image_size: number; // bytes
};

接收图像结果

当工具返回图像（例如截图或生成的图表）时，结果会包含带有 base64 编码数据的 "image" 内容块。

字段	类型	描述
`type`	`"image"`	内容块类型辨别符
`data`	`string`	Base64 编码的图像数据
`mimeType`	`string`	MIME 类型（例如 `"image/png"`）

这些图像块出现在 tool.execution_complete 事件结果中。更多信息，请参阅 Copilot SDK 中的流事件。

提示与限制

提示	详细信息
使用 PNG 或 JPEG	避免转换开销——这些图像会原样发送给 LLM
保持图像尺寸适中	大图像可能会被降低质量，导致重要细节丢失
文件附件请使用绝对路径	运行时从磁盘读取文件；相对路径可能无法正确解析
对于内存中的数据请使用 blob 附件	当你已经拥有 base64 数据（例如截图、API 响应）时，blob 可以避免不必要的磁盘 I/O
首先检查视觉支持	向不支持视觉的模型发送图像会浪费 token，且无法进行视觉理解
支持多图像	在单条消息中附加多个附件，数量上限为模型的 `max_prompt_images` 限制
不支持 SVG	SVG 文件基于文本，不在图像处理范围内

在 Copilot SDK 中使用图像输入

谁可以使用此功能？

本文内容