Utilisation d’une entrée d’image avec le Kit de développement logiciel (SDK) Copilot

Remarque

SDK Copilot est actuellement en préversion publique. Les fonctionnalités et la disponibilité sont susceptibles de changer.

Il existe deux façons d’attacher des images à une SDK Copilot session :

Pièce jointe de fichier (type: "file") : fournissez un chemin absolu ; le runtime lit le fichier à partir du disque, le convertit en base64 et l’envoie au LLM.
Pièce jointe BLOB (type: "blob") : fournissez directement des données encodées en base64 ; utile lorsque l’image est déjà en mémoire (par exemple, captures d’écran, images générées ou données provenant d’une API).

Pour obtenir un diagramme de séquence du flux d’entrée d’image, consultez le github/copilot-sdk référentiel.

Concept	Description
Pièce jointe de fichier	Une pièce jointe avec `type: "file"`et un `path` absolu vers une image sur le disque
Pièce jointe Blob	Une pièce jointe avec `type: "blob"`, encodé en base64, `data`, et un `mimeType` — aucune opération d’E/S sur le disque nécessaire
Encodage automatique	Pour les pièces jointes de fichier, le runtime lit l’image et la convertit automatiquement en base64
Redimensionnement automatique	Le runtime redimensionne automatiquement ou réduit la qualité des images qui dépassent les limites spécifiques au modèle
Capacité de vision	Le modèle doit avoir `capabilities.supports.vision = true` pour traiter des images

Guide de démarrage rapide : fichier joint

Joignez un fichier image à n’importe quel message à l’aide du type de pièce jointe de fichier. Le chemin doit être un chemin absolu vers une image sur le disque.

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

Pour obtenir des exemples dans Python, Go et .NET, consultez le github/copilot-sdk référentiel. Pour Java, consultez le github/copilot-sdk-java référentiel.

Démarrage rapide : pièce jointe blob

Lorsque vous disposez déjà de données d’image en mémoire (par exemple, une capture d’écran capturée par votre application ou une image extraite d’une API), utilisez une pièce jointe d’objet blob pour l’envoyer directement sans écrire sur le disque.

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

Pour obtenir des exemples dans Python, Go et .NET, consultez le github/copilot-sdk référentiel. Pour Java, consultez le github/copilot-sdk-java référentiel.

Formats pris en charge

Les formats d’image pris en charge incluent JPG, PNG, GIF et d’autres types d’images courants. Pour les pièces jointes de fichier, le runtime lit l’image à partir du disque et la convertit en fonction des besoins. Pour les pièces jointes de blob, vous fournissez directement les données en base64 et le type MIME. Utilisez PNG ou JPEG pour obtenir des résultats optimaux, car il s’agit des formats les plus largement pris en charge.

Le champ du capabilities.limits.vision.supported_media_types modèle répertorie les types MIME exacts qu’il accepte.

Traitement automatique

Le runtime traite automatiquement les images en fonction des contraintes du modèle. Aucun redimensionnement manuel n’est requis.

Les images qui dépassent les limites de dimension ou de taille du modèle sont automatiquement redimensionnées (avec conservation des proportions) ou réduites en qualité.
Si une image ne peut pas être réduite dans les limites après traitement, elle est ignorée et n'est pas envoyée au LLM.
Le champ capabilities.limits.vision.max_prompt_image_size du modèle indique la taille maximale de l’image en octets.

Fonctionnalités du modèle vision

Tous les modèles ne prennent pas en charge la vision. Vérifiez les fonctionnalités du modèle avant d’envoyer des images.

Champs de capacité

Champ	Type	Description
`capabilities.supports.vision`	`boolean`	Indique si le modèle peut traiter les entrées d’image
`capabilities.limits.vision.supported_media_types`	`string[]`	Types MIME que le modèle accepte (par exemple, `["image/png", "image/jpeg"]`)
`capabilities.limits.vision.max_prompt_images`	`number`	Nombre maximal d’images par invite
`capabilities.limits.vision.max_prompt_image_size`	`number`	Taille maximale de l’image en octets

Type de limites de vision

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

Réception des résultats d'image

Lorsque les outils retournent des images (par exemple, des captures d’écran ou des graphiques générés), le résultat contient des "image" blocs de contenu avec des données encodées en base64.

Champ	Type	Description
`type`	`"image"`	Discriminateur de type de bloc de contenu
`data`	`string`	Données d’image encodées en base64
`mimeType`	`string`	Type MIME (par exemple, `"image/png"`)

Ces blocs d’images apparaissent dans les tool.execution_complete résultats des événements. Pour plus d’informations, consultez « Diffusion en continu d’événements dans le Kit de développement logiciel (SDK) Copilot ».

Conseils et limitations

Conseil / Astuce	Détails
Utiliser PNG ou JPEG	Évite la surcharge de conversion : celles-ci sont envoyées telles quelles au LLM.
Conserver les images raisonnablement dimensionnées	Les grandes images peuvent être réduites de qualité, ce qui peut perdre des détails importants
Utiliser des chemins absolus pour les pièces jointes de fichier	Le runtime lit les fichiers à partir du disque ; les chemins relatifs peuvent ne pas être résolus correctement
Utiliser les pièces jointes blob pour les données en mémoire	Lorsque vous disposez déjà de données base64 (par exemple, captures d’écran, réponses d’API), l’objet blob évite les E/S de disque inutiles
Vérifiez d'abord le support de la vision	Envoyer des images à un modèle non spécialisé en vision gaspille des tokens sans apporter de compréhension visuelle.
Plusieurs images sont prises en charge	Joindre dans un message plusieurs pièces jointes, jusqu’à la limite du modèle `max_prompt_images`
SVG n’est pas pris en charge	Les fichiers SVG sont basés sur du texte et exclus du traitement d’images

Lectures complémentaires

Diffusion en continu d’événements dans le Kit de développement logiciel (SDK) Copilot : cycle de vie des événements, y compris les blocs de contenu des résultats de l’outil
Orientation et mise en file d’attente des messages dans le SDK Copilot : envoi de messages de suivi avec des pièces jointes