Verwenden von Bildeingaben mit dem Copilot SDK

Hinweis

          Copilot SDK ist zurzeit in Technische Preview. Funktionalität und Verfügbarkeit können geändert werden.

Es gibt zwei Möglichkeiten zum Anfügen von Bildern an eine Copilot SDK Sitzung:

        **Dateianlage** (`type: "file"`): Geben Sie einen absoluten Pfad an. Die Runtime liest die Datei vom Datenträger, konvertiert sie in base64 und sendet sie an das LLM.

        **Blob-Anlage** (`type: "blob"`): Stellen Sie base64-codierte Daten direkt bereit. Nützlich, wenn sich das Bild bereits im Arbeitsspeicher befindet (z. B. Screenshots, generierte Bilder oder Daten aus einer API).

Ein Sequenzdiagramm des Bildeingabeflusses finden Sie im github/copilot-sdk Repository.

Konzept	Beschreibung

          **Dateianhang** | Ein Anhang mit `type: "file"` und ein absolutes `path` Bild auf einer Festplatte |

| Blob-Anhang | Eine Anlage mit type: "blob", base64-codiertem data und einem mimeType – kein Festplatten-I/O erforderlich | | Automatische Codierung | Bei Dateianlagen liest die Laufzeit das Bild und konvertiert es automatisch in Base64. | | Automatische Größenänderung | Die Laufzeit ändert automatisch die Größe oder qualitätsmindert Bilder, die modellspezifische Grenzwerte überschreiten. | | Vision-Funktion | Das Modell muss capabilities.supports.vision = true haben, um Bilder zu verarbeiten. |

Schnellstartanleitung: Dateianhang

Fügen Sie eine Bilddatei an eine beliebige Nachricht an, indem Sie den Dateianhangstyp verwenden. Der Pfad muss ein absoluter Pfad zu einem Image auf dem Datenträger sein.

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",
        },
    ],
});

Beispiele in Python, Go und .NET finden Sie im github/copilot-sdk Repository.

Schnellstart: Blob-Anlage

Wenn Sie bereits Bilddaten im Arbeitsspeicher haben (z. B. einen Screenshot, der von Ihrer App erfasst wurde, oder ein Bild, das von einer API abgerufen wurde), verwenden Sie eine BLOB-Anlage, um sie direkt zu senden, ohne auf den Datenträger zu schreiben.

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",
        },
    ],
});

Beispiele in Python, Go und .NET finden Sie im github/copilot-sdk Repository.

Unterstützte Formate

Unterstützte Bildformate umfassen JPG, PNG, GIF und andere gängige Bildtypen. Bei Dateianhängen liest die Laufzeitumgebung das Bild vom Datenträger und konvertiert es bei Bedarf. Für Blob-Anhänge stellen Sie die Base64-Daten und den MIME-Typ direkt bereit. Verwenden Sie PNG oder JPEG, um optimale Ergebnisse zu erzielen, da dies die am häufigsten unterstützten Formate sind.

Das Feld des capabilities.limits.vision.supported_media_types Modells listet die genauen MIME-Typen auf, die es akzeptiert.

Automatische Verarbeitung

Die Laufzeit verarbeitet automatisch Bilder, die in die Einschränkungen des Modells passen. Es ist keine manuelle Größenänderung erforderlich.

Bilder, die die Größenbeschränkungen des Modells überschreiten, werden automatisch angepasst (Seitenverhältnis beibehalten) oder die Qualität wird verringert.
Wenn ein Bild nach der Verarbeitung nicht innerhalb von Grenzen gebracht werden kann, wird es übersprungen und nicht an die LLM gesendet.
Das Feld des capabilities.limits.vision.max_prompt_image_size Modells gibt die maximale Bildgröße in Bytes an.

Vision-Modellfunktionen

Nicht alle Modelle unterstützen die Bildverarbeitung. Überprüfen Sie die Funktionen des Modells, bevor Sie Bilder senden.

Funktionsfelder

Feld	Typ	Beschreibung
`capabilities.supports.vision`	`boolean`	Gibt an, ob das Modell Bildeingaben verarbeiten kann.
`capabilities.limits.vision.supported_media_types`	`string[]`	MIME-Typen, die das Modell akzeptiert (z. B `["image/png", "image/jpeg"]`. )
`capabilities.limits.vision.max_prompt_images`	`number`	Maximale Anzahl von Bildern pro Eingabeaufforderung
`capabilities.limits.vision.max_prompt_image_size`	`number`	Maximale Bildgröße in Byte

Typ der Vision-Grenzwerte

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

Empfangen von Bildergebnissen

Wenn Tools Bilder zurückgeben (z. B. Screenshots oder generierte Diagramme), enthält "image" das Ergebnis Inhaltsblöcke mit base64-codierten Daten.

Feld	Typ	Beschreibung
`type`	`"image"`	Diskriminator des Inhaltsblocktyps
`data`	`string`	Base64-codierte Bilddaten
`mimeType`	`string`	MIME-Typ (z. B `"image/png"`. )

Diese Bildblöcke werden in tool.execution_complete Ereignisergebnissen angezeigt. Weitere Informationen findest du unter Streamingereignisse im Copilot SDK.

Tipps und Einschränkungen

Tipp	Einzelheiten

          **Verwenden von PNG oder JPEG** | Vermeidung von Konvertierungsaufwand – diese werden unverändert an das LLM gesendet. |

| Halten Sie Bilder in angemessener Größe | Große Bilder können qualitätsmindert sein, was wichtige Details verlieren kann | | Verwenden Sie absolute Pfade für Dateianhänge | Die Laufzeit liest Dateien vom Datenträger, relative Pfade werden möglicherweise nicht ordnungsgemäß aufgelöst | | Verwendung von BLOB-Anhängen für im Arbeitsspeicher gehaltene Daten | Wenn Sie bereits base64-Daten haben (z. B. Screenshots, API-Antworten), vermeidet BLOB unnötige Datenträger-E/A | | Überprüfen der Sehunterstützung zuerst | Das Senden von Bildern an ein Nicht-Vision-Modell, das kein visuelles Verständnis hat, verschwendet Token. | | Mehrere Bilder werden unterstützt. | Anfügen mehrerer Anlagen in einer Nachricht bis zum Grenzwert des max_prompt_images Modells | | SVG wird nicht unterstützt | SVG-Dateien sind textbasiert und von der Bildverarbeitung ausgeschlossen. |

Weiterführende Lektüre

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/streaming-events) – Ereignislebenszyklus einschließlich Toolergebnisinhaltsblöcken

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/steering-and-queueing) – Senden von Nachverfolgungsnachrichten mit Anlagen