Verwenden von Bildeingaben mit dem Copilot SDK

Hinweis

          Copilot SDK ist zurzeit in öffentliche Vorschau. 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:

          **Dateianhang** (`type: "file"`)-geben Sie einen absoluten Pfad an; die Runtime liest die Datei vom Datenträger, wandelt sie in base64 um und sendet sie an das LLM.

          **Blob-Anhang** (`type: "blob"`)-stellt base64-kodierte Daten direkt bereit; nützlich, wenn sich das Image bereits im Arbeitsspeicher befindet (z.B. Screenshots, generierte Images oder Daten aus einer API).

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

Konzept	Beschreibung

          **Dateianhang** | Einem Anhang mit `type: "file"` und einem absoluten `path` zu einem Image auf Datenträger |

| Blob-Anhang | Ein Anhang mit type: "blob", base64-kodiert data und einem mimeType - keine E/A auf dem Datenträger erforderlich | | Automatische Codierung | Bei Dateianhängen liest die Runtime das Image 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-Anhang

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 Dimensionen oder Größenlimits des Modells überschreiten, werden automatisch in der Größe angepasst (unter Beibehaltung des Seitenverhältnisses) oder in der Qualität reduziert.
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 für den Typ der Inhaltsblöcke
`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 visuelles Modell verschwendet Token ohne visuelles Verständnis | | Mehrere Bilder werden unterstützt. | Mehrere Anhänge in einer Nachricht zuordnen, bis zum max_prompt_images Limit des 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)-Ereignis-Lebenszyklus einschließlich Tool-Ergebnis-Inhaltsblöcke

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