Outil de recherche de fichiers pour les agents

Utilisez l’outil de recherche de fichiers pour permettre à Microsoft agents Foundry de rechercher dans vos documents et de récupérer des informations pertinentes. La recherche de fichiers augmente les agents avec des connaissances provenant de l’extérieur du modèle Foundry qui alimente l’agent, comme les informations sur les produits propriétaires ou les documents fournis par l’utilisateur.

Dans cet article, vous allez apprendre à :

  • Charger des fichiers et créer un magasin de vecteurs
  • Configurer un agent avec la recherche de fichiers activée
  • Interroger vos documents via l’agent

Note

En utilisant la configuration de l’agent standard, l’outil de recherche de fichiers amélioré garantit que vos fichiers restent dans votre propre stockage. Votre Recherche Azure AI ressource ingère les fichiers, de sorte que vous conservez un contrôle total sur vos données.

Important

La recherche de fichiers entraîne des frais supplémentaires en plus des frais basés sur les jetons pour l’utilisation du modèle.

Support d'utilisation

Le tableau suivant présente la prise en charge du KIT de développement logiciel (SDK) et de la configuration.

Prise en charge de Microsoft Foundry SDK Python Kit de développement logiciel (SDK) C# Kit de développement logiciel (SDK) JavaScript Kit de développement logiciel (SDK) Java REST API Configuration de l’agent de base Configuration de l’agent standard
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Conditions préalables

  • Un environnement d’agent de base ou standard

  • Package sdk pour votre langue :

    • Python : azure-ai-projects (dernière version)
    • .NET : Azure.AI.Extensions.OpenAI
    • TypeScript : @azure/ai-projects (dernière version)
    • Java : azure-ai-agents

  • Rôle Contributeur de données Blob du stockage sur le compte de stockage de votre projet (requis pour charger des fichiers vers le stockage de votre projet)

  • Le rôle Foundry Owner sur votre ressource Foundry (requis pour créer des ressources d’agent)

    Important

    Les rôles Foundry RBAC ont été récemment renommés. Foundry User, Foundry Owner, Propriétaire du compteFoundry et Foundry Project Manager ont été précédemment nommés Azure utilisateur IA, Azure propriétaire d’IA, propriétaire Azure compte IA et Azure gestionnaire Project IA. Il se peut que vous voyiez encore les anciens noms à certains endroits pendant le déploiement de ce changement de nom. Les ID de rôle et les autorisations de base ne sont pas modifiés par ce changement de nom.

  • Azure informations d’identification configurées pour l’authentification (telles que DefaultAzureCredential).

  • URL du point de terminaison de votre projet Foundry et nom du déploiement de modèle.

Exemples de code

Les exemples suivants montrent comment charger un fichier, créer un magasin vectoriel, configurer un agent avec la recherche de fichiers activé et interroger l’agent.

Conseil

Vous pouvez personnaliser le comportement de recherche de fichiers au moment de l’exécution, par exemple spécifier le magasin de vecteurs à utiliser par requête, à l’aide d’entrées structurées.

Créer un agent avec l’outil de recherche de fichiers

L’exemple de code suivant montre comment créer un agent avec l’outil de recherche de fichiers activé. Vous devez charger des fichiers et créer un magasin de vecteurs avant d’exécuter ce code. Sélectionnez Prompt Agents pour utiliser le SDK Azure AI Projects afin de créer un agent de prompt côté serveur, ou Hosted Agents pour utiliser le framework Agent FoundryChatClient afin de créer un agent éphémère dans le processus.

from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import FileSearchTool, PromptAgentDefinition
from azure.identity import DefaultAzureCredential

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Load the file to be indexed for search.
asset_file_path = (Path(__file__).parent / "../assets/product_info.md").resolve()

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()
# The openai client uses {PROJECT_ENDPOINT}/openai/v1 for file and vector store operations

# Create vector store and upload file
vector_store = openai.vector_stores.create(name="ProductInfoStore")

with asset_file_path.open("rb") as file_handle:
    vector_store_file = openai.vector_stores.files.upload_and_poll(
        vector_store_id=vector_store.id,
        file=file_handle,
    )

# Create agent with file search tool
agent = project.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions=(
            "You are a helpful agent that can search through product information. "
            "Use file search to answer questions from the uploaded files."
        ),
        tools=[FileSearchTool(vector_store_ids=[vector_store.id])],
    ),
    description="File search agent for product information queries.",
)

# Create conversation and generate response
conversation = openai.conversations.create()

response = openai.responses.create(
    conversation=conversation.id,
    input="Tell me about Contoso products",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)

# Clean up resources
project.agents.delete_version(
    agent_name=agent.name,
    agent_version=agent.version,
)
openai.vector_stores.delete(vector_store.id)

Sortie attendue

La sortie suivante provient de l’exemple de code précédent :

[Response text grounded in your uploaded document content]

Références

Exemple de recherche de fichiers avec agent

Dans cet exemple, vous créez un fichier local, chargez-le dans Azure et utilisez-le dans le VectorStore nouvellement créé pour la recherche de fichiers. Sélectionnez Prompt Agents pour utiliser le SDK Azure AI Projects afin de créer un agent de prompt côté serveur, ou Agents hébergés pour utiliser le framework Microsoft Agent afin de créer un agent éphémère dans le processus.

Le code de cet exemple est synchrone et en streaming. Pour une utilisation asynchrone, consultez le code sample dans le Kit de développement logiciel (SDK) Azure pour .NET référentiel sur GitHub.

using System;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";

// Create project client to call Foundry API
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());

// Create a toy example file and upload it using OpenAI mechanism.
string filePath = "sample_file_for_upload.txt";
File.WriteAllText(
    path: filePath,
    contents: "The word 'apple' uses the code 442345, while the word 'banana' uses the code 673457.");
OpenAIFileClient fileClient = projectClient.ProjectOpenAIClient.GetOpenAIFileClient();
OpenAIFile uploadedFile = fileClient.UploadFile(filePath: filePath, purpose: FileUploadPurpose.Assistants);
File.Delete(filePath);

// Create the VectorStore and provide it with uploaded file ID.
VectorStoreClient vctStoreClient = projectClient.ProjectOpenAIClient.GetVectorStoreClient();
VectorStoreCreationOptions options = new()
{
    Name = "MySampleStore",
    FileIds = { uploadedFile.Id }
};
VectorStore vectorStore = vctStoreClient.CreateVectorStore(options: options);

// Create an Agent capable of using File search.
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful agent that can help fetch data from files you know about.",
    Tools = { ResponseTool.CreateFileSearchTool(vectorStoreIds: new[] { vectorStore.Id }), }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

// Ask a question about the file's contents.
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);

ResponseResult response = responseClient.CreateResponse("Can you give me the documented codes for 'banana' and 'orange'?");

// Create the response and throw an exception if the response contains the error.
Assert.That(response.Status, Is.EqualTo(ResponseStatus.Completed));
Console.WriteLine(response.GetOutputText());

// Remove all the resources created in this sample.
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
vctStoreClient.DeleteVectorStore(vectorStoreId: vectorStore.Id);
fileClient.DeleteFile(uploadedFile.Id);

Sortie attendue

La sortie suivante provient de l’exemple de code précédent :

The code for 'banana' is 673457. I couldn't find any documented code for 'orange' in the files I have access to.

Exemple de recherche de fichiers avec agent dans les scénarios de streaming

Dans cet exemple, vous créez un fichier local, chargez-le dans Azure et utilisez-le dans le VectorStore nouvellement créé pour la recherche de fichiers. Le code de cet exemple est synchrone et en streaming. Pour une utilisation asynchrone, consultez le code sample dans le Kit de développement logiciel (SDK) Azure pour .NET référentiel sur GitHub.

using System;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using OpenAI.Files;
using OpenAI.VectorStores;

class FileSearchStreamingDemo
{
    // Create a helper method ParseResponse to format streaming response output.
    // If the stream ends up in error state, it will throw an error. 
    private static void ParseResponse(StreamingResponseUpdate streamResponse)
    {
        if (streamResponse is StreamingResponseCreatedUpdate createUpdate)
        {
            Console.WriteLine($"Stream response created with ID: {createUpdate.Response.Id}");
        }
        else if (streamResponse is StreamingResponseOutputTextDeltaUpdate textDelta)
        {
            Console.WriteLine($"Delta: {textDelta.Delta}");
        }
        else if (streamResponse is StreamingResponseOutputTextDoneUpdate textDoneUpdate)
        {
            Console.WriteLine($"Response done with full message: {textDoneUpdate.Text}");
        }
        else if (streamResponse is StreamingResponseOutputItemDoneUpdate itemDoneUpdate)
        {
            if (itemDoneUpdate.Item is MessageResponseItem messageItem)
            {
                foreach (ResponseContentPart part in messageItem.Content)
                {
                    foreach (ResponseMessageAnnotation annotation in part.OutputTextAnnotations)
                    {
                        if (annotation is FileCitationMessageAnnotation fileAnnotation)
                        {
                            // Note fileAnnotation.Filename will be available in OpenAI package versions
                            // greater then 2.6.0.
                            Console.WriteLine($"File Citation - File ID: {fileAnnotation.FileId}");
                        }
                    }
                }
            }
        }
        else if (streamResponse is StreamingResponseErrorUpdate errorUpdate)
        {
            throw new InvalidOperationException($"The stream has failed with the error: {errorUpdate.Message}");
        }
    }
    public static void Main()
    {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        var projectEndpoint = "your_project_endpoint";

        // Create project client to call Foundry API
        AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());

        // Create a toy example file and upload it using OpenAI mechanism.
        string filePath = "sample_file_for_upload.txt";
        File.WriteAllText(
            path: filePath,
            contents: "The word 'apple' uses the code 442345, while the word 'banana' uses the code 673457.");
        OpenAIFile uploadedFile = projectClient.ProjectOpenAIClient.GetProjectFilesClient().UploadFile(filePath: filePath, purpose: FileUploadPurpose.Assistants);
        File.Delete(filePath);

        // Create the `VectorStore` and provide it with uploaded file ID.
        VectorStoreCreationOptions options = new()
        {
            Name = "MySampleStore",
            FileIds = { uploadedFile.Id }
        };
        VectorStore vectorStore = projectClient.ProjectOpenAIClient.GetProjectVectorStoresClient().CreateVectorStore(options);

        // Create an agent capable of using File search.
        DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
        {
            Instructions = "You are a helpful agent that can help fetch data from files you know about.",
            Tools = { ResponseTool.CreateFileSearchTool(vectorStoreIds: new[] { vectorStore.Id }), }
        };
        AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition)
        );

        // Create the conversation to store responses.
        ProjectConversation conversation = projectClient.ProjectOpenAIClient.GetProjectConversationsClient().CreateProjectConversation();
        CreateResponseOptions responseOptions = new()
        {
            Agent = agentVersion,
            AgentConversationId = conversation.Id,
            StreamingEnabled = true,
        };
        // Wait for the stream to complete.
        responseOptions.InputItems.Clear();
        responseOptions.InputItems.Add(ResponseItem.CreateUserMessageItem("Can you give me the documented codes for 'banana' and 'orange'?"));
        foreach (StreamingResponseUpdate streamResponse in projectClient.ProjectOpenAIClient.Responses.CreateResponseStreaming(responseOptions))
        {
            ParseResponse(streamResponse);
        }

        // Ask follow up question and start a new stream.
        Console.WriteLine("Demonstrating follow-up query with streaming...");
        responseOptions.InputItems.Clear();
        responseOptions.InputItems.Add(ResponseItem.CreateUserMessageItem("What was my previous question about?"));
        foreach (StreamingResponseUpdate streamResponse in projectClient.ProjectOpenAIClient.Responses.CreateResponseStreaming(responseOptions))
        {
            ParseResponse(streamResponse);
        }

        // Remove all the resources created in this sample.
        projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
        projectClient.ProjectOpenAIClient.GetProjectVectorStoresClient().DeleteVectorStore(vectorStoreId: vectorStore.Id);
        projectClient.ProjectOpenAIClient.GetProjectFilesClient().DeleteFile(uploadedFile.Id);
    }
}

Sortie attendue

La sortie suivante provient de l’exemple de code précédent :

Stream response created with ID: <response-id>
Delta: The code for 'banana' is 673457. I couldn't find any documented code for 'orange' in the files I have access to.
Response done with full message: The code for 'banana' is 673457. I couldn't find any documented code for 'orange' in the files I have access to.
File Citation - File ID: <file-id>
Demonstrating follow-up query with streaming...
Stream response created with ID: <response-id>
Delta: Your previous question was about the documented codes for 'banana' and 'orange'.
Response done with full message: Your previous question was about the documented codes for 'banana' and
'orange'.

Exemple de recherche de fichier avec agent

L’exemple TypeScript suivant montre comment créer un agent avec l’outil de recherche de fichiers activé. Vous devez charger des fichiers et créer un magasin de vecteurs avant d’exécuter ce code. Pour plus d’informations, consultez la section relative au comportement de recherche de fichiers par type d’installation de l’agent ci-dessous. Pour obtenir un exemple JavaScript, consultez le code sample dans le Kit de développement logiciel (SDK) Azure du référentiel JavaScript sur GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import * as fs from "fs";
import * as path from "path";
import { fileURLToPath } from "url";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";

export async function main(): Promise<void> {
  // Load the file to be indexed for search
  const __filename = fileURLToPath(import.meta.url);
  const __dirname = path.dirname(__filename);
  const assetFilePath = path.join(__dirname, "../assets/product_info.md");

  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  // The openai client uses {PROJECT_ENDPOINT}/openai/v1 for file and vector store operations
  const openai = project.getOpenAIClient();

  // Create vector store and upload file
  const vectorStore = await openai.vectorStores.create({
    name: "ProductInfoStore",
  });

  const fileStream = fs.createReadStream(assetFilePath);
  const file = await openai.vectorStores.files.uploadAndPoll(vectorStore.id, fileStream);

  // Create agent with file search tool
  const agent = await project.agents.createVersion("agent-file-search", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "You are a helpful assistant that can search through product information.",
    tools: [
      {
        type: "file_search",
        vector_store_ids: [vectorStore.id],
      },
    ],
  });

  // Create conversation and generate response
  const conversation = await openai.conversations.create();

  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input: "Tell me about Contoso products",
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );
  console.log(response.output_text);

  // Clean up resources
  await project.agents.deleteVersion(agent.name, agent.version);
  await openai.vectorStores.delete(vectorStore.id);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Sortie attendue

[Response text grounded in your uploaded document content]

Références

Utiliser la recherche de fichiers dans un agent Java

Ajoutez la dépendance à votre pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.0.0</version>
</dependency>

Avant d’exécuter cet exemple, créez un fichier et un magasin de vecteurs en utilisant les points de terminaison REST {projectEndpoint}/openai/v1/files et {projectEndpoint}/openai/v1/vector_stores. Consultez l’onglet REST API pour les commandes curl ou les exemples Java SDK pour obtenir un exemple complet qui inclut le chargement de fichiers.

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.ai.agents.models.FileSearchTool;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.Arrays;
import java.util.Collections;

public class FileSearchExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";
        // Create a vector store first using the {projectEndpoint}/openai/v1/vector_stores API
        String vectorStoreId = "your_vector_store_id";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint);

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();

        // Create file search tool with vector store IDs
        FileSearchTool fileSearchTool = new FileSearchTool(
            Arrays.asList(vectorStoreId)
        );

        // Create agent with file search tool
        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini")
            .setInstructions("You are a helpful assistant that can search through files to answer questions.")
            .setTools(Collections.singletonList(fileSearchTool));

        AgentVersionDetails agent = agentsClient.createAgentVersion("file-search-agent", agentDefinition);
        System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());

        // Create a response
        AgentReference agentReference = new AgentReference(agent.getName())
            .setVersion(agent.getVersion());

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions().setAgentReference(agentReference),
            ResponseCreateParams.builder()
                .input("What information is in the uploaded files?"));

        System.out.println("Response: " + response.output());

        // Clean up
        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
    }
}

Sortie attendue

Agent created: file-search-agent (version 1)
Response: [ResponseOutputItem containing file search results ...]

Pour plus d'exemples, notamment le chargement de fichiers et la création de magasin de vecteurs, consultez les exemples Azure AI Agents Java SDK.

Charger des fichiers et les ajouter à un magasin vectoriel

Pour accéder à vos fichiers, l’outil de recherche de fichiers utilise l’objet de magasin de vecteurs. Chargez vos fichiers et créez un magasin de vecteurs. Sondez ensuite l’état du stockage jusqu’à ce que tous les fichiers soient hors de l’état in_progress afin de vérifier que tout le contenu est entièrement traité. Le Kit de développement logiciel (SDK) fournit des assistances pour le chargement et l’interrogation.

Définissez la variable d’environnement suivante avant d’exécuter les exemples :

export AGENT_TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv)

Charger un fichier

curl --request POST \
  --url $FOUNDRY_PROJECT_ENDPOINT/openai/v1/files \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -F purpose="assistants" \
  -F file="@c:\\path_to_file\\sample_file_for_upload.txt"

Créer un magasin de vecteurs

curl --request POST \
  --url $FOUNDRY_PROJECT_ENDPOINT/openai/v1/vector_stores \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_vector_store",
    "file_ids": ["'$FILE_ID'"]
  }'

Créer un agent avec l’outil de recherche de fichiers

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "<AGENT_NAME>-file-search",
    "description": "Agent with file search",
    "definition": {
      "kind": "prompt",
      "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
      "tools": [
        {
          "type": "file_search",
          "vector_store_ids": ["'$VECTOR_STORE_ID'"],
          "max_num_results": 20
        }
      ],
      "instructions": "You are a customer support chatbot. Use file search results from the vector store to answer questions based on the uploaded files."
    }
  }'

curl --request POST \
  --url $FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "agent": {
    "type": "agent_reference",
    "name": "<AGENT_NAME>-file-search"
  },
  "metadata": {
    "test_response": "file_search_enabled",
    "vector_store_id": "'$VECTOR_STORE_ID'"
  },
  "input": [{
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Can you search the uploaded file and tell me about Azure TV instructions?"
      }
    ]
  }],
  "stream": true
}'

La réponse retourne la sortie de streaming contenant la réponse de l’agent en fonction des informations récupérées à partir de la base de vecteurs. L’agent effectue une recherche dans votre fichier chargé pour répondre à la requête concernant les instructions pour Azure TV.

Nettoyer

Supprimez l’agent.

curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/agents/<AGENT_NAME>-file-search?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN"

Supprimez le magasin de vecteurs.

curl --request DELETE \
  --url $FOUNDRY_PROJECT_ENDPOINT/openai/v1/vector_stores/$VECTOR_STORE_ID \
  -H "Authorization: Bearer $AGENT_TOKEN"

Supprimez le fichier.

curl --request DELETE \
  --url $FOUNDRY_PROJECT_ENDPOINT/openai/v1/files/$FILE_ID \
  -H "Authorization: Bearer $AGENT_TOKEN"

Références

Vérifier les résultats de la recherche de fichiers

Après avoir exécuté un exemple de code dans cet article, vérifiez que la recherche de fichiers fonctionne :

  • Vérifiez que le magasin de vecteurs et le fichier sont créés.
    • Dans les exemples Python et TypeScript, les utilitaires de chargement et d’interrogation se terminent uniquement une fois que l'ingestion est achevée.
  • Posez une question que vous ne pouvez répondre qu’à partir de votre contenu chargé.
  • Vérifiez que la réponse est ancrée dans vos documents.

Sources de fichiers

  • Charger des fichiers locaux (configuration de l’agent de base et standard)
  • Stockage Blob Azure (configuration standard uniquement)

Comportement de recherche de fichiers par type de configuration de l’agent

Configuration de l’agent de base

L’outil de recherche de fichiers dispose des mêmes fonctionnalités que Azure’API Réponses OpenAI. L’outil utilise Microsoft ressources de recherche managée et de stockage.

  • Vous stockez des fichiers chargés dans Microsoft stockage managé.
  • Vous créez un magasin de vecteurs à l’aide d’une ressource de recherche managée Microsoft.

Configuration de l’agent standard

L’outil de recherche de fichiers utilise les ressources Recherche Azure AI et Stockage Blob Azure auxquelles vous vous connectez pendant la configuration de l’agent.

  • Vous stockez des fichiers chargés dans votre compte de Stockage Blob Azure connecté.
  • Vous créez des magasins de vecteurs à l’aide de votre ressource de Recherche Azure AI connectée.

Pour les deux configurations de l’agent, le service gère l’ensemble du processus d’ingestion, notamment :

  • Analyse et segmentation automatique des documents.
  • Génération et stockage d'embeddings.
  • Utilisation de recherches vectorielles et de mots clés pour récupérer du contenu pertinent pour les requêtes utilisateur.

Le code est identique pour les deux configurations. La seule variante est l’emplacement où sont stockés vos fichiers et magasins vectoriels.

Choisissez la recherche de fichiers lorsque vous devez :

  • Effectuer une recherche dans des documents que vous chargez directement (fichiers PDF, Word docs, fichiers de code)
  • Permettre aux agents de répondre à des questions à partir de contenu propriétaire ou confidentiel
  • Traiter des fichiers jusqu’à 512 Mo sans gérer l’infrastructure de recherche externe

Tenez compte des alternatives pour ces scénarios :

Scénario Outil recommandé
Rechercher des index de Recherche Azure AI existants Outil de recherche Azure AI
Rechercher les informations actuelles sur le web public Outil de recherche web
Combiner plusieurs sources de données dans une requête Utiliser plusieurs outils ensemble

Fonctionnement de la recherche de fichiers

L’outil de recherche de fichiers utilise les meilleures pratiques de récupération pour extraire les données pertinentes de vos fichiers et améliorer les réponses de modèle.

Traitement des requêtes

Lorsque vous envoyez une requête, recherche de fichiers :

  1. Réécrit votre requête pour l’optimiser pour la recherche.
  2. Décompose les requêtes complexes en recherches parallèles.
  3. Exécute la recherche hybride combinant mot clé et correspondance sémantique entre les magasins vectoriels.
  4. Reclasse les résultats pour sélectionner le contenu le plus pertinent pour la réponse.

Paramètres de segmentation par défaut

Réglage Valeur par défaut
Taille de bloc 800 jetons
Chevauchement de segments 400 jetons
Modèle d’incorporation text-embedding-3-large (256 dimensions)
Nombre maximal de blocs dans le contexte 20

Bases de données de vecteurs

Les objets de magasin de vecteurs donnent à l’outil de recherche de fichiers la possibilité de rechercher vos fichiers. Lorsque vous ajoutez un fichier à un magasin de vecteurs, le processus analyse automatiquement, segmente, incorpore et stocke le fichier dans une base de données vectorielle qui prend en charge à la fois la recherche par mots-clés et la recherche sémantique. Chaque magasin de vecteurs peut contenir jusqu’à 10 000 fichiers. Vous pouvez associer des magasins de vecteurs aux agents et aux conversations. Actuellement, vous pouvez associer au maximum un magasin de vecteurs à un agent et au maximum un magasin de vecteurs à une conversation.

Pour obtenir des concepts d’arrière-plan et des conseils de cycle de vie (préparation, comportement de suppression et stratégies d’expiration), consultez Les magasins Vector pour la recherche de fichiers.

Supprimez les fichiers d'un stockage de vecteurs par :

  • Suppression de l’objet de fichier de stockage de vecteurs.
  • Suppression de l’objet de fichier sous-jacent. Cette action supprime le fichier de toutes les configurations vector_store et code_interpreter des agents et conversations de votre organisation.

La taille maximale du fichier est de 512 Mo. Chaque fichier ne doit contenir pas plus de 5 000 000 jetons (calculés automatiquement lorsque vous joignez un fichier).

Garantir la préparation du magasin vectoriel avant la création d’exécutions

Assurez-vous que le système traite entièrement tous les fichiers d’un magasin vectoriel avant de créer une exécution. Cela garantit que toutes les données de votre magasin vectoriel peuvent faire l’objet d’une recherche. Vérifiez la disponibilité du stockage de vecteurs à l'aide des outils de sondage dans les SDK, ou en sondant manuellement l'objet de stockage de vecteurs pour vous assurer que l'état est terminé.

En guise de secours, l’objet d’exécution inclut une attente maximale de 60 secondes lorsque le magasin vectoriel de la conversation contient des fichiers qui sont toujours en cours de traitement. Cette attente garantit que tous les fichiers que vos utilisateurs chargent dans une conversation sont complètement consultables avant que le processus ne se poursuive. Cette période d'attente de secours ne s'applique pas au magasin de vecteurs de l'agent.

Les magasins de vecteurs de conversation ont des stratégies d’expiration par défaut

Les magasins vectoriels que vous créez à l’aide d’assistances de conversation (comme tool_resources.file_search.vector_stores dans les conversations ou message.attachments dans messages) ont une stratégie d’expiration par défaut de sept jours après leur dernière activité (définie comme la dernière fois que le magasin vectoriel faisait partie d’une exécution).

Lorsqu’un magasin de vecteurs expire, les exécutions sur cette conversation échouent. Pour résoudre ce problème, recréez un nouveau magasin de vecteurs avec les mêmes fichiers et rattachez-le à la conversation.

Types de fichiers pris en charge

Note

Pour les types MIME de texte, l’encodage doit être UTF-8, UTF-16 ou ASCII.

Format de fichier Type MIME
.c text/x-c
.cs text/x-csharp
.cpp text/x-c++
.doc application/msword
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html text/html
.java text/x-java
.json application/json
.md text/markdown
.pdf application/pdf
.php text/x-php
.pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
.py text/x-python
.py text/x-script.python
.rb text/x-ruby
.tex text/x-tex
.txt text/plain
.css text/css
.js text/javascript
.sh application/x-sh
.ts application/typescript

Limitations

Gardez ces limites à l’esprit lorsque vous planifiez l’intégration de votre recherche de fichiers :

  • La recherche de fichiers prend en charge des formats et encodages de fichiers spécifiques. Consultez les types de fichiers pris en charge.
  • Chaque magasin de vecteurs peut contenir jusqu’à 10 000 fichiers.
  • Vous pouvez associer au maximum un magasin de vecteurs à un agent et au maximum un magasin de vecteurs à une conversation.
  • Les fonctionnalités et la disponibilité varient selon la région. Consultez la prise en charge régionale d'Azure AI Foundry.

Dépannage

Problème Cause probable Résolution
401 Non autorisé Le jeton d’accès est manquant, expiré ou limité de manière incorrecte. Obtenez un nouveau jeton et réessayez la requête. Pour les appels REST, vérifiez que vous avez correctement défini AGENT_TOKEN .
403 Interdit L’identité de connexion n’a pas les rôles requis. Confirmez les rôles dans Prérequis et réessayez une fois les attributions de rôles terminées.
404 Introuvable Les identificateurs de point de terminaison ou de ressource du projet sont incorrects. Confirmez FOUNDRY_PROJECT_ENDPOINT et des ID tels que le nom de l’agent, la version, l'ID du magasin de vecteurs et l'ID de fichier.
Les réponses ignorent vos fichiers L’agent n’est pas configuré avec file_search, ou le magasin vectoriel n’est pas attaché. Vérifiez que la définition de l’agent inclut file_search et que la vector_store_ids liste contient votre ID de magasin de vecteurs.
Le chargement du fichier expire Connexion réseau volumineuse ou lente. Utilisez upload_and_poll pour gérer les gros fichiers. Envisagez de segmenter des documents très volumineux.
Échec de la création du magasin de vecteurs Le quota est dépassé ou le format de fichier est invalide. Vérifiez les limites du magasin de vecteurs (10 000 fichiers par magasin). Vérifiez que le format de fichier est pris en charge.
La recherche retourne des résultats non pertinents Le contenu du fichier n'est pas correctement indexé ou la requête est trop large. Attendez que l’indexation se termine (vérification vector_store.status). Utilisez des requêtes plus spécifiques.
Aucune citation en réponse Le modèle n’a pas utilisé la recherche de fichiers ou le contenu introuvable. Utilisez tool_choice="required" pour forcer la recherche de fichiers. Vérifiez que le contenu du fichier correspond à votre rubrique de requête.

Contenu connexe

  • Last updated on