将图像输入与 Copilot SDK 配合使用

注意

          Copilot SDK 当前处于 技术预览版. 功能和可用性可能会发生更改。

可通过两种方法将图像附加到 Copilot SDK 会话：

        **文件附件** （`type: "file"`）- 提供绝对路径;运行时从磁盘读取文件，将其转换为 base64，并将其发送到 LLM。

        **Blob 附件** （`type: "blob"`）- 直接提供 base64 编码的数据;当图像已在内存中时非常有用（例如，屏幕截图、生成的图像或 API 中的数据）。

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

概念	说明

          **文件附件** | 磁盘上含有`type: "file"`的附件和绝对`path`的图像 |

快速入门：文件附件

使用文件附件类型将图像文件附加到任何邮件。该路径必须是磁盘上映像的绝对路径。

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 存储库。

快速入门：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 存储库。

支持的格式

支持的图像格式包括 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
};

接收图像处理结果

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

领域	类型	说明
`type`	`"image"`	内容块类型鉴别器
`data`	`string`	Base64 编码的图像数据
`mimeType`	`string`	MIME 类型（例如， `"image/png"`）

这些图像块显示在事件结果 tool.execution_complete 中。有关详细信息，请参阅“Copilot SDK 中的流式处理事件”。

提示和限制

小窍门	详细信息

          **使用 PNG 或 JPEG** | 避免转换开销 - 这些内容会原样发送到 LLM |

延伸阅读

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/streaming-events) - 事件生命周期，包括工具结果内容块

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/steering-and-queueing) - 发送带有附件的跟进邮件

谁可以使用此功能？

在本文中