Azure OpenAI Yardımcıları dosya arama aracı (Önizleme) (klasik)

Yalnızca şunlar için geçerlidir:Dökümhane (klasik) portalı. Bu makale yeni Dökümhane portalında kullanılamaz. Yeni portal hakkında daha fazla bilgi edinin.

Not

Bu makaledeki bağlantılar, şu anda görüntülediğiniz Dökümhane (klasik) belgeleri yerine yeni Microsoft Foundry belgelerinde içerik açabilir.

Not

Asistanlar API'si kullanımdan kaldırıldı ve 26 Ağustos 2026'da emekliye ayrılacaktır. Genel olarak mevcut olan Microsoft Foundry Agents hizmetini kullanın. İş yüklerinizi güncellemek için geçiş rehberini takip edin. Daha fazla bilgi edinin.

Dosya Arama, Yardımcı'yı modeli dışından, özel ürün bilgileri veya kullanıcılarınız tarafından sağlanan belgeler gibi bilgilerle genişleter. OpenAI, belgelerinizi otomatik olarak ayrıştırıp öbekler, eklemeleri oluşturup depolar ve kullanıcı sorgularını yanıtlamak üzere ilgili içeriği almak için hem vektör hem de anahtar sözcük aramasını kullanır.

Önemli

  • Dosya araması, Azure OpenAI kullanımı için belirteç tabanlı ücretlerin ötesinde ek ücretler içerir.

Dosya arama desteği

Desteklenen bölgeler

Dosya arama, Yardımcıları destekleyen bölgelerde kullanılabilir.

API Sürümü

  • 2024-05-01-önizleme sürümünden başlayarak

Desteklenen dosya türleri

Not

Metin/MIME türleri için kodlama utf-8, utf-16 veya ASCII olmalıdır.

Dosya biçimi MIME Türü
.C text/x-c
.cs text/x-csharp
.cpp text/x-c++
.doc application/msword
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html metin/html
.java text/x-java
.json application/json
.md text/markdown
.pdf uygulama/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 düz metin
.css text/css
.js text/javascript
.sh application/x-sh
.ts application/typescript 
from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant = client.beta.assistants.create(
  name="Financial Analyst Assistant",
  instructions="You are an expert financial analyst. Use your knowledge base to answer questions about audited financial statements.",
  model="gpt-4-turbo",
  tools=[{"type": "file_search"}],
)

Dosyalarınıza erişmek için dosya arama aracı vektör deposu nesnesini kullanır. Dosyalarınızı karşıya yükleyin ve bunları içerecek bir vektör deposu oluşturun. Vektör deposu oluşturulduktan sonra, tüm içeriğin işlenmesinin tamamlandığından in_progress emin olmak için tüm dosyalar durum dışına çıkana kadar durumunu yoklamanız gerekir. SDK, yükleme ve yoklama için araçlar sağlar.

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

# Create a vector store called "Financial Statements"
vector_store = client.beta.vector_stores.create(name="Financial Statements")
 
# Ready the files for upload to OpenAI
file_paths = ["mydirectory/myfile1.pdf", "mydirectory/myfile2.txt"]
file_streams = [open(path, "rb") for path in file_paths]
 
# Use the upload and poll SDK helper to upload the files, add them to the vector store,
# and poll the status of the file batch for completion.
file_batch = client.beta.vector_stores.file_batches.upload_and_poll(
  vector_store_id=vector_store.id, files=file_streams
)
 
# You can print the status and the file counts of the batch to see the result of this operation.
print(file_batch.status)
print(file_batch.file_counts)

Yardımcıyı yeni vektör depoyu kullanacak şekilde güncelleştirme

Dosyaların yardımcınız tarafından erişilebilir olmasını sağlamak için yardımcının tool_resources kimliğini yeni vector_store kimlikle güncelleştirin.

assistant = client.beta.assistants.update(
  assistant_id=assistant.id,
  tool_resources={"file_search": {"vector_store_ids": [vector_store.id]}},
)

Konu oluştur

Dosyaları iş parçacığınıza İleti eki olarak da ekleyebilirsiniz. Bunu yaptığınızda iş parçacığıyla ilişkilendirilmiş başka bir vector_store öğe oluşturulur veya bu iş parçacığına eklenmiş bir vektör deposu varsa, yeni dosyaları mevcut iş parçacığı vektör deposuna ekleyin. Bu iş parçacığında bir Çalışma oluşturduğunuzda, dosya arama aracı hem yardımcınızdan hem de iş parçacığında vector_store ve vector_store sorgulayacak.

# Upload the user provided file to OpenAI
message_file = client.files.create(
  file=open("mydirectory/myfile.pdf", "rb"), purpose="assistants"
)
 
# Create a thread and attach the file to the message
thread = client.beta.threads.create(
  messages=[
    {
      "role": "user",
      "content": "How many company shares were outstanding last quarter?",
      # Attach the new file to the message.
      "attachments": [
        { "file_id": message_file.id, "tools": [{"type": "file_search"}] }
      ],
    }
  ]
)
 
# The thread now has a vector store with that file in its tool resources.
print(thread.tool_resources.file_search)

Vektör depoları, en son etkin olduktan sonraki yedi günlük varsayılan süre sonu ilkesine sahip ileti ekleri kullanılarak oluşturulur (vektör deposunun bir çalıştırmanın parçası olduğu son zaman olarak tanımlanır). Vektör depolama maliyetlerinizi yönetmenize yardımcı olması için bu varsayılan değer vardır. Bu süre sonu ilkelerini istediğiniz zaman geçersiz kılabilirsiniz.

Bir çalışma oluştur ve çıktıyı kontrol et

Bir Çalıştırma oluşturun ve modelin kullanıcının sorusuna yanıt sağlamak için dosya arama aracını kullandığını gözlemleyin.

from typing_extensions import override
from openai import AssistantEventHandler, OpenAI
 
client = OpenAI()
 
class EventHandler(AssistantEventHandler):
    @override
    def on_text_created(self, text) -> None:
        print(f"\nassistant > ", end="", flush=True)

    @override
    def on_tool_call_created(self, tool_call):
        print(f"\nassistant > {tool_call.type}\n", flush=True)

    @override
    def on_message_done(self, message) -> None:
        # print a citation to the file searched
        message_content = message.content[0].text
        annotations = message_content.annotations
        citations = []
        for index, annotation in enumerate(annotations):
            message_content.value = message_content.value.replace(
                annotation.text, f"[{index}]"
            )
            if file_citation := getattr(annotation, "file_citation", None):
                cited_file = client.files.retrieve(file_citation.file_id)
                citations.append(f"[{index}] {cited_file.filename}")

        print(message_content.value)
        print("\n".join(citations))

# Then, we use the stream SDK helper
# with the EventHandler class to create the Run
# and stream the response.

with client.beta.threads.runs.stream(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
    event_handler=EventHandler(),
) as stream:
    stream.until_done()

Nasıl çalışır?

Dosya arama aracı, dosyalarınızdan doğru verileri ayıklamanıza ve modelin yanıtlarını artırmanıza yardımcı olmak için doğrudan çeşitli en iyi alma yöntemlerini uygular. file_search aracı:

  • Arama için en iyi duruma getirmek için kullanıcı sorgularını yeniden yazar.
  • Karmaşık kullanıcı sorgularını paralel olarak çalıştırabileceği birden çok aramaya ayırır.
  • Hem asistan hem de iş parçacığı vektör depolarında hem anahtar sözcük hem de anlamsal aramalar çalıştırır.
  • Son yanıtı oluşturmadan önce en uygun sonuçları seçmek için arama sonuçlarını yeniden düzenler.
  • Varsayılan olarak, dosya arama aracı aşağıdaki ayarları kullanır:
    • Öbek boyutu: 800 token
    • Öbek çakışması: 400 belirteç
    • Ekleme modeli: 256 boyutta metin ekleme-3-büyük
    • Bağlam içine eklenen parça sayısının üst sınırı: 20

Vektör depoları

Vektör deposu nesneleri, dosya arama aracına dosyalarınızda arama yapma olanağı verir. Vektör deposuna dosya eklemek, dosyayı otomatik olarak ayrıştırır, öbekler oluşturur, içine yerleştirir ve hem anahtar sözcük hem de anlamsal arama yapabilen bir vektör veritabanında depolar. Her vektör deposu en fazla 10.000 dosya barındırabilir. Vektör depoları hem Yardımcılara hem de Thread'lere eklenebilir. Şu anda bir yardımcıya en fazla bir vektör deposu ve bir iş parçacığına en fazla bir vektör deposu ekleyebilirsiniz.

Vektör depoları oluşturma ve dosya ekleme

Tek bir API çağrısında bir vektör deposu oluşturabilir ve bu depoya dosya ekleyebilirsiniz:

vector_store = client.beta.vector_stores.create(
  name="Product Documentation",
  file_ids=['file_1', 'file_2', 'file_3', 'file_4', 'file_5']
)

Vektör depolarına dosya eklemek zaman uyumsuz bir işlemdir. İşlemin tamamlandığından emin olmak için resmi SDK'larımızda 'oluştur ve yokla' yardımcılarını kullanmanızı öneririz. SDK'ları kullanmıyorsanız, vector_store nesnesini alabilir ve dosya alma işleminin sonucunu görmek için file_counts özelliğini izleyebilirsiniz.

Dosyalar, vektör deposu dosyaları oluşturularak oluşturulduktan sonra bir vektör deposuna da eklenebilir.

file = client.beta.vector_stores.files.create_and_poll(
  vector_store_id="vs_abc123",
  file_id="file-abc123"
)

Alternatif olarak, en fazla 500 dosyadan oluşan toplu işlemler oluşturarak vektör deposuna birkaç dosya ekleyebilirsiniz.

batch = client.beta.vector_stores.file_batches.create_and_poll(
  vector_store_id="vs_abc123",
  file_ids=['file_1', 'file_2', 'file_3', 'file_4', 'file_5']
)

Benzer şekilde, bu dosyalar bir vektör deposundan aşağıdakilerden biri tarafından kaldırılabilir:

  • Vektör deposu dosya nesnesini silme veya
  • Temel dosya nesnesini silerek dosyayı kuruluşunuzdaki tüm yardımcılar ve iş parçacıklarındaki tüm vector_store ve code_interpreter yapılandırmalarından tamamen kaldırırsınız.

Dosya boyutu üst sınırı 512 MB'tır. Her dosya, dosya başına en fazla 5.000.000 belirteç içermelidir (dosya eklediğinizde otomatik olarak hesaplanır).

Vektör depoları ekleme

tool_resources parametresini kullanarak Yardımcınıza veya İş Parçacığı (Thread)'ınıza vektör veritabanları ekleyebilirsiniz.

assistant = client.beta.assistants.create(
  instructions="You are a helpful product support assistant and you answer questions based on the files provided to you.",
  model="gpt-4-turbo",
  tools=[{"type": "file_search"}],
  tool_resources={
    "file_search": {
      "vector_store_ids": ["vs_1"]
    }
  }
)

thread = client.beta.threads.create(
  messages=[ { "role": "user", "content": "How do I cancel my subscription?"} ],
  tool_resources={
    "file_search": {
      "vector_store_ids": ["vs_2"]
    }
  }
)

Ayrıca, oluşturulduktan sonra doğru tool_resources ile güncelleştirerek Threads veya Yardımcılara bir vektör deposu ekleyebilirsiniz.

Çalıştırmalar oluşturmadan önce vektör deposunun hazır olma durumunu sağlama

Bir çalıştırma oluşturmadan önce, vector_store içindeki tüm dosyaların tam olarak işlendiğinden kesinlikle emin olmanız önerilir. Bu, vektör deponuzdaki tüm verilerin aranabilir olmasını sağlar. SDK'lardaki yoklama yardımcılarını kullanarak veya durumun tamamlandığından emin olmak için nesneyi el ile yoklayarak vector_store vektör deposu hazır olup olmadığını de kontrol edebilirsiniz.

Yedek önlem olarak, iş parçacığının vektör deposunda işlem aşamasındaki dosyalar bulunduğunda çalıştırma nesnesinde en fazla 60 saniyelik bir bekleme olur. Bu, çalıştırma devam etmeden önce kullanıcılarınızın iş parçacığında karşıya yüklediği tüm dosyaların tamamen aranabilir olmasını sağlamaktır. Bu geri dönüş beklemesi yardımcının vektör deposu için geçerli değildir.

Süre sonu ilkeleriyle maliyetleri yönetme

Araç file_search, vector_stores nesneyi kaynak olarak kullanır ve oluşturulan *vector_store* nesnelerinin boyutlarına göre faturalandırılırsınız. Vektör deposu nesnesinin boyutu, dosyalarınızdaki tüm ayrıştırılan öbeklerin ve buna karşılık gelen eklemelerin toplamıdır.

Bu vector_store nesneleriyle ilişkili maliyetleri yönetmenize yardımcı olmak için nesneye vector_store süre sonu ilkeleri desteği ekledik. Nesneyi oluştururken veya güncelleştirirken vector_store bu ilkeleri ayarlayabilirsiniz.

vector_store = client.beta.vector_stores.create_and_poll(
  name="Product Documentation",
  file_ids=['file_1', 'file_2', 'file_3', 'file_4', 'file_5'],
  expires_after={
	  "anchor": "last_active_at",
	  "days": 7
  }
)

İş parçacığı vektör depolarının varsayılan süre sonu politikaları vardır.

İş parçacığı yardımcıları kullanılarak oluşturulan vektör depoları (İş Parçacıklarında veya tool_resources.file_search.vector_stores İletilerde olduğu gibimessage.attachments) en son etkin olduktan sonraki yedi günlük varsayılan süre sonu ilkesine sahiptir (vektör deposunun bir çalıştırmanın son parçası olduğu zaman olarak tanımlanır).

Vektör deposunun süresi dolduğunda, o iş parçacığındaki çalıştırmalar başarısız olur. Bunu düzeltmek için, aynı dosyalarla yeni bir vector_store yeniden oluşturabilir ve iş parçacığına yeniden ekleyebilirsiniz.

all_files = list(client.beta.vector_stores.files.list("vs_expired"))

vector_store = client.beta.vector_stores.create(name="rag-store")
client.beta.threads.update(
    "thread_abc123",
    tool_resources={"file_search": {"vector_store_ids": [vector_store.id]}},
)

for file_batch in chunked(all_files, 100):
    client.beta.vector_stores.file_batches.create_and_poll(
        vector_store_id=vector_store.id, file_ids=[file.id for file in file_batch]
    )
  • Last updated on