{"meta":{"title":"图像输入","intro":"将图像作为附件发送到Copilot会话。 可通过两种方法附加图像：","product":"GitHub Copilot","breadcrumbs":[{"href":"/zh/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos","title":"操作方法"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features","title":"功能"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/image-input","title":"图像输入"}],"documentType":"article"},"body":"# 图像输入\n\n将图像作为附件发送到Copilot会话。 可通过两种方法附加图像：\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n* **文件附件** （`type: \"file\"`）：提供绝对路径;运行时从磁盘读取文件，将其转换为 base64，并将其发送到 LLM。\n* **Blob 附件** （`type: \"blob\"`）：直接提供 base64 编码的数据;当图像已在内存中时非常有用（例如屏幕截图、生成的图像或 API 中的数据）。\n\n## 概述\n\n![关系图：显示描述的过程的序列图。](/assets/images/help/copilot/copilot-sdk/features-image-input-diagram-0.png)\n\n| 概念                                                            | Description                                         |\n| ------------------------------------------------------------- | --------------------------------------------------- |\n| **文件附件**                                                      |                                                     |\n| `type: \"file\"` 的附件和磁盘上图像的绝对 `path`                            |                                                     |\n| **Blob 附件**                                                   |                                                     |\n| `type: \"blob\"`、base64 编码的 `data` 和 `mimeType` 的附件 - 不需要磁盘 I/O |                                                     |\n| **自动编码**                                                      | 对于文件附件，运行时将读取图像并将其自动转换为 base64                      |\n| **自动调整大小**                                                    | 运行时会自动调整图像的大小，或降低超出模型特定限制的图像的质量。                    |\n| **视觉功能**                                                      | 模型必须具有 `capabilities.supports.vision = true` 才能处理图像 |\n\n## 快速入门 - 文件附件\n\n使用文件附件类型将图像文件附加到任何邮件。 该路径必须是磁盘上映像的绝对路径。\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient();\nawait client.start();\n\nconst session = await client.createSession({\n    model: \"gpt-5.4\",\n    onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n\nawait session.send({\n    prompt: \"Describe what you see in this image\",\n    attachments: [\n        {\n            type: \"file\",\n            path: \"/absolute/path/to/screenshot.png\",\n        },\n    ],\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot import CopilotClient, PermissionDecisionApproveOnce\n\nclient = CopilotClient()\nawait client.start()\n\nsession = await client.create_session(\n    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n    model=\"gpt-5.4\",\n)\n\nawait session.send(\n    \"Describe what you see in this image\",\n    attachments=[\n        {\n            \"type\": \"file\",\n            \"path\": \"/absolute/path/to/screenshot.png\",\n        },\n    ],\n)\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nctx := context.Background()\nclient := copilot.NewClient(nil)\nclient.Start(ctx)\n\nsession, _ := client.CreateSession(ctx, &copilot.SessionConfig{\n    Model: \"gpt-5.4\",\n    OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {\n        return &rpc.PermissionDecisionApproveOnce{}, nil\n    },\n})\n\npath := \"/absolute/path/to/screenshot.png\"\nsession.Send(ctx, copilot.MessageOptions{\n    Prompt: \"Describe what you see in this image\",\n    Attachments: []copilot.Attachment{\n        &copilot.AttachmentFile{\n            DisplayName: \"screenshot.png\",\n            Path:        path,\n        },\n    },\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nusing GitHub.Copilot;\nusing GitHub.Copilot.Rpc;\n\nawait using var client = new CopilotClient();\nawait using var session = await client.CreateSessionAsync(new SessionConfig\n{\n    Model = \"gpt-5.4\",\n    OnPermissionRequest = (req, inv) =>\n        Task.FromResult(PermissionDecision.ApproveOnce()),\n});\n\nawait session.SendAsync(new MessageOptions\n{\n    Prompt = \"Describe what you see in this image\",\n    Attachments = new List<Attachment>\n    {\n        new AttachmentFile\n        {\n            Path = \"/absolute/path/to/screenshot.png\",\n            DisplayName = \"screenshot.png\",\n        },\n    },\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\nimport java.util.List;\n\ntry (var client = new CopilotClient()) {\n    client.start().get();\n\n    var session = client.createSession(\n        new SessionConfig()\n            .setModel(\"gpt-5.4\")\n            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n    ).get();\n\n    session.send(new MessageOptions()\n        .setPrompt(\"Describe what you see in this image\")\n        .setAttachments(List.of(\n            new Attachment(\"file\", \"/absolute/path/to/screenshot.png\", \"screenshot.png\")\n        ))\n    ).get();\n}\n```\n\n</div>\n\n</div>\n\n## 快速入门 — Blob 附件\n\n如果内存中已有图像数据（例如应用捕获的屏幕截图或从 API 提取的图像），请使用 blob 附件直接发送它，而无需写入磁盘。\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient();\nawait client.start();\n\nconst session = await client.createSession({\n    model: \"gpt-5.4\",\n    onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n\nconst base64ImageData = \"...\"; // your base64-encoded image\nawait session.send({\n    prompt: \"Describe what you see in this image\",\n    attachments: [\n        {\n            type: \"blob\",\n            data: base64ImageData,\n            mimeType: \"image/png\",\n            displayName: \"screenshot.png\",\n        },\n    ],\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot import CopilotClient, PermissionDecisionApproveOnce\n\nclient = CopilotClient()\nawait client.start()\n\nsession = await client.create_session(\n    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n    model=\"gpt-5.4\",\n)\n\nbase64_image_data = \"...\"  # your base64-encoded image\nawait session.send(\n    \"Describe what you see in this image\",\n    attachments=[\n        {\n            \"type\": \"blob\",\n            \"data\": base64_image_data,\n            \"mimeType\": \"image/png\",\n            \"displayName\": \"screenshot.png\",\n        },\n    ],\n)\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nmimeType := \"image/png\"\ndisplayName := \"screenshot.png\"\nsession.Send(ctx, copilot.MessageOptions{\n    Prompt: \"Describe what you see in this image\",\n    Attachments: []copilot.Attachment{\n        &copilot.AttachmentBlob{\n            Data:        &base64ImageData, // base64-encoded string\n            MIMEType:    mimeType,\n            DisplayName: &displayName,\n        },\n    },\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nawait session.SendAsync(new MessageOptions\n{\n    Prompt = \"Describe what you see in this image\",\n    Attachments = new List<Attachment>\n    {\n        new AttachmentBlob\n        {\n            Data = base64ImageData,\n            MimeType = \"image/png\",\n            DisplayName = \"screenshot.png\",\n        },\n    },\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\nimport java.util.List;\n\ntry (var client = new CopilotClient()) {\n    client.start().get();\n\n    var session = client.createSession(\n        new SessionConfig()\n            .setModel(\"gpt-5.4\")\n            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n    ).get();\n\n    var base64ImageData = \"...\"; // your base64-encoded image\n    session.send(new MessageOptions()\n        .setPrompt(\"Describe what you see in this image\")\n        .setAttachments(List.of(\n            new BlobAttachment()\n                .setData(base64ImageData)\n                .setMimeType(\"image/png\")\n                .setDisplayName(\"screenshot.png\")\n        ))\n    ).get();\n}\n```\n\n</div>\n\n</div>\n\n## 支持的格式\n\n支持的图像格式包括 JPG、PNG、GIF 和其他常见图像类型。 对于文件附件，运行时从磁盘读取映像，并根据需要转换映像。 对于 Blob 附件，可以直接提供 base64 数据和 MIME 类型。 使用 PNG 或 JPEG 获得最佳效果，因为这些格式是支持最广泛的格式。\n\n模型的字段列出了它接受的 `capabilities.limits.vision.supported_media_types` 确切 MIME 类型。\n\n## 自动处理\n\n运行时会自动处理图像以适应模型的约束。 无需手动调整大小。\n\n* 超出模型尺寸或大小限制的图像会自动调整大小（保留纵横比）或降低质量。\n* 如果图像在处理后仍无法在限制范围内，则会跳过该图像，并且不会将其发送到 LLM。\n* 模型的 `capabilities.limits.vision.max_prompt_image_size` 字段指示最大图像大小（以字节为单位）。\n\n可以通过模型功能对象在运行时检查这些限制。 为了获得最佳体验，请使用大小合理的 PNG 或 JPEG 图像。\n\n## 视觉模型功能\n\n并非所有模型都支持视觉。 在发送图像之前检查模型的功能。\n\n### 功能字段\n\n| 领域                                                 | 类型         | Description                                     |\n| -------------------------------------------------- | ---------- | ----------------------------------------------- |\n| `capabilities.supports.vision`                     | `boolean`  | 模型是否可以处理图像输入                                    |\n| `capabilities.limits.vision.supported_media_types` | `string[]` | 模型接受的 MIME 类型（例如 `[\"image/png\", \"image/jpeg\"]`） |\n| `capabilities.limits.vision.max_prompt_images`     | `number`   | 每个提示的最大图像数                                      |\n| `capabilities.limits.vision.max_prompt_image_size` | `number`   | 最大图像大小（以字节为单位）                                  |\n\n### 视觉限制类型\n\n```typescript\nvision?: {\n    supported_media_types: string[];\n    max_prompt_images: number;\n    max_prompt_image_size: number; // bytes\n};\n```\n\n## 接收图像处理结果\n\n当工具返回图像（例如屏幕截图或生成的图表）时，结果包含 `\"image\"` 具有 base64 编码数据的内容块。\n\n| 领域         | 类型        | Description               |\n| ---------- | --------- | ------------------------- |\n| `type`     | `\"image\"` | 内容块类型鉴别器                  |\n| `data`     | `string`  | Base64 编码的图像数据            |\n| `mimeType` | `string`  | MIME 类型（例如） `\"image/png\"` |\n\n这些图像块显示在事件结果 `tool.execution_complete` 中。 有关完整的事件生命周期，请参阅 [流式处理会话事件](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/streaming-events) 指南。\n\n## 提示和限制\n\n| Tip                     | 详细信息                                             |\n| ----------------------- | ------------------------------------------------ |\n| **直接使用 PNG 或 JPEG**     | 避免转换开销 - 这些内容会原样发送到 LLM                          |\n| **使图像保持合理大小**           | 大型图像可能会质量降低，这可能会丢失重要细节                           |\n| **对文件附件使用绝对路径**         | 运行时从磁盘读取文件;相对路径可能无法正确解析                          |\n| **使用 BLOB 附件来处理内存中的数据** | 如果已有 base64 数据（例如屏幕截图、API 响应），Blob 将避免不必要的磁盘 I/O |\n| **首先检查视觉支持**            | 将图像发送到没有视觉理解能力的非视觉模型会浪费标记。                       |\n| **支持多个映像**              | 在一个消息中附加若干附件，直到达到模型的 `max_prompt_images` 限制      |\n| **不支持 SVG**             | SVG 文件基于文本，并且从图像处理中排除                            |\n\n## 另见\n\n* [流式处理会话事件](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/streaming-events)：事件生命周期，包括工具结果内容块\n* [引导和排队](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/steering-and-queueing)：发送带有附件的跟进邮件"}