Cara mengunggah file menggunakan alat pencarian file

2025-07-02

Gunakan artikel ini untuk menemukan instruksi langkah demi langkah dan sampel kode untuk mengunggah file menggunakan alat pencarian file.

Prasyarat

Selesaikan penyiapan agen.
Pastikan Anda memiliki peran Kontributor Data Blob Penyimpanan di akun penyimpanan proyek Anda.
Pastikan Anda memiliki peran Pengembang Azure AI di proyek Anda.

Menambahkan pencarian file ke agen menggunakan portal Azure AI Foundry

Buka portal Azure AI Foundry. Di layar Agen untuk agen Anda, gulir ke bawah panel Penyiapan di sebelah kanan ke pengetahuan. Kemudian pilih Tambahkan.
Pilih File dan ikuti perintah untuk menambahkan alat.

Membuat klien proyek

Buat objek klien yang berisi titik akhir untuk menyambungkan ke proyek AI Anda dan sumber daya lainnya.

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

# Define the project endpoint
project_endpoint = os.environ["PROJECT_ENDPOINT"]  # Ensure the PROJECT_ENDPOINT environment variable is set

# Initialize the AIProjectClient
project_client = AIProjectClient(
    endpoint=project_endpoint,
    credential=DefaultAzureCredential(exclude_interactive_browser_credential=False),  # Use Azure Default Credential for authentication
    api_version="latest",
)

Mengunggah file dan menambahkannya ke Penyimpanan Vektor

Untuk mengakses file Anda, alat pencarian file menggunakan objek penyimpanan vektor. Unggah file Anda dan buat penyimpanan vektor.

from azure.ai.agents.models import FilePurpose

# Define the path to the file to be uploaded
file_path = "./data/product_info_1.md"

# Upload the file
file = project_client.agents.files.upload_and_poll(file_path=file_path, purpose=FilePurpose.AGENTS)
print(f"Uploaded file, file ID: {file.id}")

# Create a vector store with the uploaded file
vector_store = project_client.agents.vector_stores.create_and_poll(file_ids=[file.id], name="my_vectorstore")
print(f"Created vector store, vector store ID: {vector_store.id}")

Membuat agen dan mengaktifkan pencarian file

Untuk membuat file dapat diakses oleh agen Anda, buat FileSearchTool objek dengan vector_store ID, dan lampirkan alat dan tool_resources ke agen.

from azure.ai.agents.models import FileSearchTool

# Create a file search tool
file_search = FileSearchTool(vector_store_ids=[vector_store.id])

# Create an agent with the file search tool
agent = project_client.agents.create_agent(
    model=os.environ["MODEL_DEPLOYMENT_NAME"],  # Model deployment name
    name="my-agent",  # Name of the agent
    instructions="You are a helpful agent and can search information from uploaded files",  # Instructions for the agent
    tools=file_search.definitions,  # Tools available to the agent
    tool_resources=file_search.resources,  # Resources for the tools
)
print(f"Created agent, ID: {agent.id}")

Buat utas

Anda juga dapat melampirkan file sebagai lampiran pesan di utas Anda. Melakukannya membuat yang lain vector_store yang terkait dengan utas, atau, jika sudah ada penyimpanan vektor yang dilampirkan ke utas ini, melampirkan file baru ke penyimpanan vektor utas yang ada.

# Create a thread
thread = project_client.agents.threads.create()
print(f"Created thread, ID: {thread.id}")

# Send a message to the thread
message = project_client.agents.messages.create(
    thread_id=thread.id,
    role="user",
    content="Hello, what Contoso products do you know?",  # Message content
)
print(f"Created message, ID: {message['id']}")

Membuat eksekusi dan memeriksa output

Buat eksekusi dan amati bahwa model menggunakan alat pencarian file untuk memberikan respons.

# Create and process an agent run in the thread
run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
print(f"Run finished with status: {run.status}")

if run.status == "failed":
    print(f"Run failed: {run.last_error}")

# Cleanup resources
project_client.agents.vector_stores.delete(vector_store.id)
print("Deleted vector store")

project_client.agents.delete_file(file_id=file.id)
print("Deleted file")

project_client.agents.delete_agent(agent.id)
print("Deleted agent")

# Fetch and log all messages from the thread
messages = project_client.agents.messages.list(thread_id=thread.id)
file_name = os.path.split(file_path)[-1]
for msg in messages:
    if msg.text_messages:
        last_text = msg.text_messages[-1].text.value
        for annotation in msg.text_messages[-1].text.annotations:
            citation = (
                file_name if annotation.file_citation.file_id == file.id else annotation.file_citation.file_id
            )
            last_text = last_text.replace(annotation.text, f" [{citation}]")
        print(f"{msg.role}: {last_text}")

Membuat klien proyek

Buat objek klien yang berisi titik akhir untuk menyambungkan ke proyek AI Anda dan sumber daya lainnya.

using Azure;
using Azure.AI.Agents.Persistent;
using Azure.Identity;
using Microsoft.Extensions.Configuration;
using System;
using System.Collections.Generic;
using System.Threading;

// Get Connection information from app configuration
IConfigurationRoot configuration = new ConfigurationBuilder()
    .SetBasePath(AppContext.BaseDirectory)
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .Build();

var projectEndpoint = configuration["ProjectEndpoint"];
var modelDeploymentName = configuration["ModelDeploymentName"];

// Create the Agent Client
PersistentAgentsClient agentClient = new(projectEndpoint, new DefaultAzureCredential());

Mengunggah file dan menambahkannya ke Penyimpanan Vektor

Untuk mengakses file Anda, alat pencarian file menggunakan objek penyimpanan vektor. Unggah file Anda dan buat penyimpanan vektor. Setelah membuat penyimpanan vektor, periksa statusnya sampai semua file diunggah untuk memastikan bahwa seluruh konten telah sepenuhnya diproses. SDK menyediakan pembantu untuk mengunggah dan melakukan polling.

// Create a local sample file
System.IO.File.WriteAllText(
    path: "sample_file_for_upload.txt",
    contents: "The word 'apple' uses the code 442345, while the word 'banana' uses the code 673457."
);

// Upload local sample file to the agent
PersistentAgentFileInfo uploadedAgentFile = agentClient.Files.UploadFile(
    filePath: "sample_file_for_upload.txt",
    purpose: PersistentAgentFilePurpose.Agents
);

// Setup dictionary with list of File IDs for the vector store
Dictionary<string, string> fileIds = new()
{
    { uploadedAgentFile.Id, uploadedAgentFile.Filename }
};

// Create a vector store with the file and wait for it to be processed.
// If you do not specify a vector store, CreateMessage will create a vector
// store with a default expiration policy of seven days after they were last active
PersistentAgentsVectorStore vectorStore = agentClient.VectorStores.CreateVectorStore(
    fileIds: new List<string> { uploadedAgentFile.Id },
    name: "my_vector_store");

Membuat agen dan mengaktifkan pencarian file

Buat objek alat pencarian berkas dengan ID penyimpanan vektor, dan lampirkan alat serta sumber daya alat ke agen.

// Create tool definition for File Search
FileSearchToolResource fileSearchToolResource = new FileSearchToolResource();
fileSearchToolResource.VectorStoreIds.Add(vectorStore.Id);

// Create an agent with Tools and Tool Resources
PersistentAgent agent = agentClient.Administration.CreateAgent(
        model: modelDeploymentName,
        name: "SDK Test Agent - Retrieval",
        instructions: "You are a helpful agent that can help fetch data from files you know about.",
        tools: new List<ToolDefinition> { new FileSearchToolDefinition() },
        toolResources: new ToolResources() { FileSearch = fileSearchToolResource });

Buat utas dan memulai

Anda juga dapat melampirkan file sebagai Lampiran pesan di utas Anda. Melakukannya membuat penyimpanan vektor lain yang terkait dengan utas, atau, jika sudah ada penyimpanan vektor yang terpasang pada utas ini, melampirkan file baru ke penyimpanan vektor utas yang ada. Saat Anda membuat Jalankan pada utas ini, alat pencarian file meminta penyimpanan vektor dari agen Anda dan penyimpanan vektor di utas.

// Create the agent thread for communication
PersistentAgentThread thread = agentClient.Threads.CreateThread();

// Create message and run the agent
PersistentThreadMessage messageResponse = agentClient.Messages.CreateMessage(
    thread.Id,
    MessageRole.User,
    "Can you give me the documented codes for 'banana' and 'orange'?");

ThreadRun run = agentClient.Runs.CreateRun(thread, agent);

Tunggu penyelesaian proses dan periksa status

Tunggu hingga agen berjalan untuk menyelesaikan pemrosesan dengan melakukan polling statusnya. Amati bahwa model menggunakan alat pencarian file untuk memberikan respons.

// Wait for the agent to finish running
do
{
    Thread.Sleep(TimeSpan.FromMilliseconds(500));
    run = agentClient.Runs.GetRun(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued
    || run.Status == RunStatus.InProgress);

// Confirm that the run completed successfully
if (run.Status != RunStatus.Completed)
{
    throw new Exception("Run did not complete successfully, error: " + run.LastError?.Message);
}

Memproses pesan dan menangani kutipan

Setelah operasi selesai, ambil pesan dari thread dan memproses pesan tersebut, mengganti referensi file dengan nama file yang sebenarnya.

// Retrieve all messages from the agent client
Pageable<PersistentThreadMessage> messages = agentClient.Messages.GetMessages(
    threadId: thread.Id,
    order: ListSortOrder.Ascending
);

// Helper method for replacing references
static string replaceReferences(Dictionary<string, string> fileIds, string fileID, string placeholder, string text)
{
    if (fileIds.TryGetValue(fileID, out string replacement))
        return text.Replace(placeholder, $" [{replacement}]");
    else
        return text.Replace(placeholder, $" [{fileID}]");
}

// Process messages in order
foreach (PersistentThreadMessage threadMessage in messages)
{
    Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");

    foreach (MessageContent contentItem in threadMessage.ContentItems)
    {
        if (contentItem is MessageTextContent textItem)
        {
            if (threadMessage.Role == MessageRole.Agent && textItem.Annotations.Count > 0)
            {
                string strMessage = textItem.Text;

                // If we file path or file citation annotations - rewrite the 'source' FileId with the file name
                foreach (MessageTextAnnotation annotation in textItem.Annotations)
                {
                    if (annotation is MessageTextFilePathAnnotation pathAnnotation)
                    {
                        strMessage = replaceReferences(fileIds, pathAnnotation.FileId, pathAnnotation.Text, strMessage);
                    }
                    else if (annotation is MessageTextFileCitationAnnotation citationAnnotation)
                    {
                        strMessage = replaceReferences(fileIds, citationAnnotation.FileId, citationAnnotation.Text, strMessage);
                    }
                }
                Console.Write(strMessage);
            }
            else
            {
                Console.Write(textItem.Text);
            }
        }
        else if (contentItem is MessageImageFileContent imageFileItem)
        {
            Console.Write($"<image from ID: {imageFileItem.FileId}");
        }
        Console.WriteLine();
    }
}

Membersihkan sumber daya

Bersihkan sumber daya dari sampel ini.

// Clean up resources
agentClient.VectorStores.DeleteVectorStore(vectorStore.Id);
agentClient.Files.DeleteFile(uploadedAgentFile.Id);
agentClient.Threads.DeleteThread(thread.Id);
agentClient.Administration.DeleteAgent(agent.Id);

Membuat klien proyek

Buat objek klien yang berisi titik akhir untuk menyambungkan ke proyek AI Anda dan sumber daya lainnya.

const { AgentsClient, isOutputOfType, ToolUtility } = require("@azure/ai-agents");
const { delay } = require("@azure/core-util");
const { DefaultAzureCredential } = require("@azure/identity");

const fs = require("fs");
require("dotenv/config");

const projectEndpoint = process.env["PROJECT_ENDPOINT"];

// Create an Azure AI Client
const client = new AgentsClient(projectEndpoint, new DefaultAzureCredential());

Mengunggah file dan menambahkannya ke Penyimpanan Vektor

Unggah file Anda dan buat penyimpanan vektor.

// Upload file
const filePath = "./data/sampleFileForUpload.txt";
const localFileStream = fs.createReadStream(filePath);
const file = await client.files.upload(localFileStream, "assistants", {
  fileName: "sampleFileForUpload.txt",
});
console.log(`Uploaded file, file ID: ${file.id}`);

// Create vector store
const vectorStore = await client.vectorStores.create({
  fileIds: [file.id],
  name: "myVectorStore",
});
console.log(`Created vector store, vector store ID: ${vectorStore.id}`);

Membuat agen dan mengaktifkan pencarian file

Buat fileSearchTool objek dengan ID penyimpanan vektor, dan lampirkan tools dan toolResources ke agen.

// Initialize file search tool
const fileSearchTool = ToolUtility.createFileSearchTool([vectorStore.id]);

// Create agent with files
const agent = await client.createAgent(modelDeploymentName, {
  name: "SDK Test Agent - Retrieval",
  instructions: "You are helpful agent that can help fetch data from files you know about.",
  tools: [fileSearchTool.definition],
  toolResources: fileSearchTool.resources,
});
console.log(`Created agent, agent ID : ${agent.id}`);

Buat utas

// Create thread
const thread = await client.threads.create();
console.log(`Created thread, thread ID: ${thread.id}`);

// Create message
const message = await client.messages.create(
  thread.id,
  "user",
  "Can you give me the documented codes for 'banana' and 'orange'?",
);
console.log(`Created message, message ID: ${message.id}`);

Membuat eksekusi dan memeriksa output

Buat eksekusi dan amati bahwa model menggunakan alat pencarian file untuk memberikan respons.

// Create run
let run = await client.runs.create(thread.id, agent.id);
while (["queued", "in_progress"].includes(run.status)) {
  await delay(500);
  run = await client.runs.get(thread.id, run.id);
  console.log(`Current Run status - ${run.status}, run ID: ${run.id}`);
}

console.log(`Current Run status - ${run.status}, run ID: ${run.id}`);
const messages = await client.messages.list(thread.id);
for await (const threadMessage of messages) {
  console.log(
    `Thread Message Created at  - ${threadMessage.createdAt} - Role - ${threadMessage.role}`,
  );
  threadMessage.content.forEach((content) => {
    if (isOutputOfType(content, "text")) {
      const textContent = content;
      console.log(`Text Message Content - ${textContent.text.value}`);
    } else if (isOutputOfType(content, "image_file")) {
      const imageContent = content;
      console.log(`Image Message Content - ${imageContent.imageFile.fileId}`);
    }
  });
}

// Delete agent
await client.deleteAgent(agent.id);
console.log(`Deleted agent, agent ID: ${agent.id}`);

Mengunggah file dan menambahkannya ke penyimpanan vektor

Untuk mengakses file Anda, alat pencarian file menggunakan objek penyimpanan vektor. Unggah file Anda dan buat penyimpanan vektor. Setelah membuat penyimpanan vektor, periksa statusnya sampai semua file tidak lagi berada dalam status in_progress untuk memastikan bahwa semua konten sepenuhnya diproses. SDK menyediakan pembantu untuk mengunggah dan melakukan polling.

Ikuti Mulai Cepat REST API untuk mengatur nilai yang tepat untuk AGENT_TOKEN variabel lingkungan, AZURE_AI_FOUNDRY_PROJECT_ENDPOINT, dan API_VERSION.

Mengunggah file

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/files?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -F purpose="assistants" \
  -F file="@c:\\path_to_file\\sample_file_for_upload.txt"

Membuat penyimpanan vektor

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/vector_stores?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_vector_store"
  }'

Lampirkan file yang diunggah ke penyimpanan vektor

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/vector_stores/vs_abc123/files?api-version=$API_VERSION \
    -H "Authorization: Bearer $AGENT_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "file_id": "assistant-abc123"
    }'

Membuat agen dan mengaktifkan pencarian file

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/assistants?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Financial Analyst Assistant",
    "instructions": "You are an expert financial analyst. Use your knowledge base to answer questions about audited financial statements.",
    "tools": [{"type": "file_search"}],
    "model": "gpt-4o-mini",
    "tool_resources": {"file_search": {"vector_store_ids": ["vs_1234abcd"]}}
  }'

Buat utas

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''

Tambahkan pertanyaan pengguna ke topik

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "user",
      "content": "Which months do we have covered in the financial statements?"
    }'

Membuat eksekusi dan memeriksa output

Buat eksekusi dan amati bahwa model menggunakan alat pencarian file untuk memberikan respons.

Jalankan thread

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

Mengambil status proses

curl --request GET \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN"

Dapatkan respons agen

curl --request GET \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN"

Bagikan melalui

Cara mengunggah file menggunakan alat pencarian file

Prasyarat

Menambahkan pencarian file ke agen menggunakan portal Azure AI Foundry

Membuat klien proyek

Mengunggah file dan menambahkannya ke Penyimpanan Vektor

Membuat agen dan mengaktifkan pencarian file

Buat utas

Membuat eksekusi dan memeriksa output

Membuat klien proyek

Mengunggah file dan menambahkannya ke Penyimpanan Vektor

Membuat agen dan mengaktifkan pencarian file

Buat utas dan memulai

Tunggu penyelesaian proses dan periksa status

Memproses pesan dan menangani kutipan

Membersihkan sumber daya

Membuat klien proyek

Mengunggah file dan menambahkannya ke Penyimpanan Vektor

Membuat agen dan mengaktifkan pencarian file

Buat utas

Membuat eksekusi dan memeriksa output

Mengunggah file dan menambahkannya ke penyimpanan vektor

Mengunggah file

Membuat penyimpanan vektor

Lampirkan file yang diunggah ke penyimpanan vektor

Membuat agen dan mengaktifkan pencarian file

Buat utas

Tambahkan pertanyaan pengguna ke topik

Membuat eksekusi dan memeriksa output

Jalankan thread

Mengambil status proses

Dapatkan respons agen

Saran dan Komentar

Sumber Daya Tambahan: