البحث داخل الملفات في OpenAI API لا يعني إرسال مستند كامل مع كل سؤال. تتيح أداة file_search في Responses API استرجاع معلومات من ملفات سبق رفعها وفهرستها، باستخدام البحث الدلالي والكلمات المفتاحية. وللتخطيط لتطبيقات 2027، يشرح هذا الدليل تجهيز الفهرس، وإظهار نتائج البحث، وضبط النطاق، ومتابعة حذف الملفات وفق الوثائق المتاحة في 27 أكتوبر 2026، دون افتراض مواصفات أو أسعار مستقبلية.
ما الفرق بين الملف ومخزن البحث؟
يمثل كائن file المحتوى المرفوع عبر Files API. أما vector_store فهو الحاوية التي تضم الملفات القابلة للبحث. وعند إضافة ملف إليها، تنشأ علاقة vector_store.file، ثم يقسم محتواه إلى مقاطع وتحسب تمثيلاتها وتفهرس. رفع الملف وحده لا يعني أن معالجة البحث انتهت.
يمكن استخدام مخزن المتجهات بطريقتين مختلفتين: تبحث مباشرة عبر Retrieval API لتحصل على المقاطع ودرجات التشابه ومصدرها، أو تتيح أداة file_search للنموذج ضمن Responses API ليبحث ويصوغ الإجابة. في الحالة الثانية تتولى الخدمة تنفيذ الأداة عندما يقرر النموذج استخدامها؛ لا تفترض أن مجرد إتاحتها يعني أنها استدعيت في كل رد.
تجهيز قاعدة الملفات قبل الأسئلة
- ارفع الملف عبر Files API، واحتفظ بمعرفه.
- أنشئ مخزن متجهات، ثم أضف الملف إليه.
- انتظر اكتمال المعالجة وتحقق من الحالة completed؛ ويمكن استخدام مساعد مثل create_and_poll للعملية غير المتزامنة.
- أرسل طلب Responses يتضمن أداة من النوع file_search ومعرفات المخازن في vector_store_ids.
من الصيغ المدعومة PDF وDOCX وPPTX وTXT وMarkdown وعدد من ملفات الشيفرة. الحد الأعلى للملف 512 ميجابايت، وبحد خمسة ملايين رمز لكل ملف، يحسب عند إرفاقه. أما الملفات النصية من نوع text/ فتحتاج ترميز UTF-8 أو UTF-16 أو ASCII.
الاستشهاد بالملف ليس عرض نتائج البحث
عندما تستدعى الأداة، تتضمن المخرجات عنصر file_search_call وعنصر رسالة قد يحتوي على إحالات file_citation، منها معرف الملف واسمه. لكن نتائج البحث نفسها لا تعاد افتراضيًا مع استدعاء الأداة. لطلبها، أضف include بقيمة تتضمن file_search_call.results عند إنشاء الرد.
يفيد الفصل عند الاختبار: افحص هل استدعيت الأداة أصلًا، وما الملفات التي أشارت إليها الرسالة، ثم راجع المقاطع المسترجعة عند تضمينها. وجود اسم ملف في الإجابة لا يغني عن التأكد من أن المقطع يدعم الادعاء، ولا يثبت أن الملف هو أحدث نسخة من السياسة.
عدد النتائج والمرشحات
يمكن تقليل عدد النتائج عبر max_num_results. قد يقلل ذلك استهلاك الرموز والزمن، لكنه قد يخفض جودة الإجابة إذا أخفى مقاطع لازمة. اختبر أسئلة تحتاج أكثر من جزء من المستند، لا سؤالًا بسيطًا فقط، قبل تثبيت قيمة صغيرة.
يمكن كذلك تضييق البحث بسمات الملفات attributes ومرشحات filters، مثل حصره في قسم أو منطقة أو فترة. السمات تضاف إلى علاقة الملف بالمخزن. وإذا أردت التصفية باسم ملف بوصفه سمة مخصصة، فعليك تعيين سمة filename صراحة؛ لا تفترض أنها تطابق اسم الملف المرفوع تلقائيًا.
وهذه المرشحات لا تعفي التطبيق من ضبط الوصول: حدد المخازن والسمات المسموح بها من صلاحيات المستخدم، ولا تعتمد على أن يطلب المستخدم القسم الصحيح في السؤال. مثال توضيحي: سؤال عن سياسة فرع الرياض لا ينبغي أن يبحث في مسودة قديمة لفرع آخر ثم يعاملها كسياسة نافذة.
التحديث والحذف والتكلفة
إزالة ملف من مخزن المتجهات ليست فورية الاتساق؛ قد تظهر مقاطع منه في نتائج البحث لفترة قصيرة بعد الإزالة. لذلك اختبر نتائج الاسترجاع بعد تحديث سياسة مهمة، ولا تعتبر نجاح طلب الإزالة وحده دليلًا على اختفاء المحتوى من البحث فورًا.
يمكن تعيين انتهاء صلاحية للمخزن عبر expires_after، ومن أمثلته ربط عدد الأيام بآخر نشاط عبر last_active_at. عند انتهاء المخزن تحذف علاقات vector_store.file المرتبطة به ويتوقف احتساب تكلفتها. لا تخلط ذلك مع إثبات حذف كل كائن file أصلي أو نسخة تحتفظ بها داخل تطبيقك؛ تتبع كل طبقة على حدة، وراجع تكلفة التخزين الناتجة عن المقاطع والتمثيلات لا حجم الملف الأصلي وحده.
