رفع الملفات إلى تخزين المتجهات

تحميل محتوى الملف إلى Vector Store مع عمليات الدفعة

post

Upload files to a vector store.

Path parameters

vector-store-idstringRequired

The ID of the vector store.

Header parameters

x-api-keystringRequired

The API key for authentication.

Body

filesstring · binary[]Optional

The files to upload.

Responses

201

Files uploaded successfully.

application/json

207

Some files failed to upload.

post

HTTPcURLJavaScriptPython

POST /api/v1/vector-stores/{vector-store-id}/documents/upload HTTP/1.1
Host: api.rememberizer.ai
x-api-key: text
Content-Type: multipart/form-data
Accept: */*
Content-Length: 20

{
  "files": [
    "binary"
  ]
}

{
  "documents": [
    {
      "id": 1,
      "name": "text"
    }
  ],
  "errors": [
    {
      "file": "text",
      "error": "text"
    }
  ]
}

طلبات مثال

cURL

curl -X POST \
  https://api.rememberizer.ai/api/v1/vector-stores/vs_abc123/documents/upload \
  -H "x-api-key: YOUR_API_KEY" \
  -F "files=@/path/to/document1.pdf" \
  -F "files=@/path/to/document2.docx"

استبدل YOUR_API_KEY بمفتاح API الفعلي لمتجر المتجهات الخاص بك، و vs_abc123 بمعرف متجر المتجهات الخاص بك، وقدم المسارات إلى ملفاتك المحلية.

JavaScript

const uploadFiles = async (vectorStoreId, files) => {
  const formData = new FormData();
  
  // إضافة ملفات متعددة إلى بيانات النموذج
  for (const file of files) {
    formData.append('files', file);
  }
  
  const response = await fetch(`https://api.rememberizer.ai/api/v1/vector-stores/${vectorStoreId}/documents/upload`, {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY'
      // ملاحظة: لا تقم بتعيين رأس Content-Type، سيتم تعيينه تلقائيًا مع الحدود الصحيحة
    },
    body: formData
  });
  
  const data = await response.json();
  console.log(data);
};

// مثال على الاستخدام مع عنصر إدخال الملف
const fileInput = document.getElementById('fileInput');
uploadFiles('vs_abc123', fileInput.files);

استبدل YOUR_API_KEY بمفتاح API الفعلي لمتجر المتجهات الخاص بك و vs_abc123 بمعرف متجر المتجهات الخاص بك.

Python

import requests

def upload_files(vector_store_id, file_paths):
    headers = {
        "x-api-key": "YOUR_API_KEY"
    }
    
    files = [('files', (file_path.split('/')[-1], open(file_path, 'rb'))) for file_path in file_paths]
    
    response = requests.post(
        f"https://api.rememberizer.ai/api/v1/vector-stores/{vector_store_id}/documents/upload",
        headers=headers,
        files=files
    )
    
    data = response.json()
    print(data)

upload_files('vs_abc123', ['/path/to/document1.pdf', '/path/to/document2.docx'])

استبدل YOUR_API_KEY بمفتاح API الفعلي لمتجر المتجهات الخاص بك، و vs_abc123 بمعرف متجر المتجهات الخاص بك، وقدم المسارات إلى ملفاتك المحلية.

Ruby

require 'net/http'
require 'uri'
require 'json'

def upload_files(vector_store_id, file_paths)
  uri = URI("https://api.rememberizer.ai/api/v1/vector-stores/#{vector_store_id}/documents/upload")
  
  # إنشاء كائن HTTP جديد
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  
  # إنشاء طلب multipart-form
  request = Net::HTTP::Post.new(uri)
  request['x-api-key'] = 'YOUR_API_KEY'
  
  # إنشاء حد multipart
  boundary = "RubyFormBoundary#{rand(1000000)}"
  request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
  
  # بناء جسم الطلب
  body = []
  file_paths.each do |file_path|
    file_name = File.basename(file_path)
    file_content = File.read(file_path, mode: 'rb')
    
    body << "--#{boundary}\r\n"
    body << "Content-Disposition: form-data; name=\"files\"; filename=\"#{file_name}\"\r\n"
    body << "Content-Type: #{get_content_type(file_name)}\r\n\r\n"
    body << file_content
    body << "\r\n"
  end
  body << "--#{boundary}--\r\n"
  
  request.body = body.join
  
  # إرسال الطلب
  response = http.request(request)
  
  # تحليل وإرجاع الاستجابة
  JSON.parse(response.body)
end

طريقة مساعدة لتحديد نوع المحتوى

def get_content_type(filename) ext = File.extname(filename).downcase case ext when '.pdf' then 'application/pdf' when '.doc' then 'application/msword' when '.docx' then 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' when '.txt' then 'text/plain' when '.md' then 'text/markdown' when '.json' then 'application/json' else 'application/octet-stream' end end

مثال على الاستخدام

result = upload_files('vs_abc123', ['/path/to/document1.pdf', '/path/to/document2.docx']) puts result

<div data-gb-custom-block data-tag="hint" data-style='info'>

استبدل `YOUR_API_KEY` بمفتاح API الخاص بك لـ Vector Store، و `vs_abc123` بمعرف Vector Store الخاص بك، وقدم المسارات إلى ملفاتك المحلية.

</div>

</div>

</div>

## معلمات المسار

| المعلمة | النوع | الوصف |
|-----------|------|-------------|
| vector-store-id | سلسلة | **مطلوب.** معرف متجر المتجهات لتحميل الملفات إليه. |

## جسم الطلب

تقبل هذه النقطة النهائية طلب `multipart/form-data` مع ملف واحد أو أكثر في حقل `files`.

## صيغة الاستجابة

```json
{
  "documents": [
    {
      "id": 1234,
      "name": "document1.pdf",
      "type": "application/pdf",
      "size": 250000,
      "status": "processing",
      "created": "2023-06-15T10:15:00Z",
      "vector_store": "vs_abc123"
    },
    {
      "id": 1235,
      "name": "document2.docx",
      "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "size": 180000,
      "status": "processing",
      "created": "2023-06-15T10:15:00Z",
      "vector_store": "vs_abc123"
    }
  ],
  "errors": []
}

إذا فشلت بعض الملفات في التحميل، فسيتم إدراجها في مصفوفة errors:

{
  "documents": [
    {
      "id": 1234,
      "name": "document1.pdf",
      "type": "application/pdf",
      "size": 250000,
      "status": "processing",
      "created": "2023-06-15T10:15:00Z",
      "vector_store": "vs_abc123"
    }
  ],
  "errors": [
    {
      "file": "document2.docx",
      "error": "تنسيق الملف غير مدعوم"
    }
  ]
}

المصادقة

تتطلب هذه النقطة النهائية المصادقة باستخدام مفتاح API في رأس x-api-key.

تنسيقات الملفات المدعومة

• PDF (.pdf)

• Microsoft Word (.doc, .docx)

• Microsoft Excel (.xls, .xlsx)

• Microsoft PowerPoint (.ppt, .pptx)

• ملفات نصية (.txt)

• Markdown (.md)

• JSON (.json)

• HTML (.html, .htm)

حدود حجم الملف

• حد حجم الملف الفردي: 50MB

• حد حجم الطلب الإجمالي: 100MB

• الحد الأقصى لعدد الملفات في كل طلب: 20

ردود الخطأ

رمز الحالة	الوصف
400	طلب غير صحيح - لم يتم تقديم ملفات أو تنسيق طلب غير صالح
401	غير مصرح - مفتاح API غير صالح أو مفقود
404	غير موجود - لم يتم العثور على متجر المتجهات
413	الحمولة كبيرة جدًا - الملفات تتجاوز حد الحجم
415	نوع الوسائط غير مدعوم - تنسيق الملف غير مدعوم
500	خطأ في الخادم الداخلي
207	حالة متعددة - تم تحميل بعض الملفات بنجاح، لكن فشلت أخرى

حالة المعالجة

يتم قبول الملفات في البداية بحالة processing. يمكنك التحقق من حالة معالجة الوثائق باستخدام نقطة النهاية الحصول على قائمة بالوثائق في متجر المتجهات. ستكون الحالة النهائية واحدة من:

• done: تم معالجة الوثيقة بنجاح

• error: حدث خطأ أثناء المعالجة

• processing: لا تزال الوثيقة قيد المعالجة

تعتمد مدة المعالجة على حجم الملف وتعقيده. تتراوح مدة المعالجة النموذجية بين 30 ثانية إلى 5 دقائق لكل وثيقة.

العمليات الدفعة

لرفع عدة ملفات إلى متجر المتجهات الخاص بك بكفاءة، يدعم Rememberizer العمليات الدفعة. تساعد هذه الطريقة في تحسين الأداء عند التعامل مع أعداد كبيرة من الوثائق.

تنفيذ تحميل دفعة

Python

import os
import requests
import time
import concurrent.futures
from pathlib import Path

def batch_upload_to_vector_store(vector_store_id, folder_path, batch_size=5, file_types=None):
    """
    تحميل جميع الملفات من دليل إلى متجر المتجهات على دفعات
    
    Args:
        vector_store_id: معرف متجر المتجهات
        folder_path: مسار المجلد الذي يحتوي على الملفات المراد تحميلها
        batch_size: عدد الملفات التي سيتم تحميلها في كل دفعة
        file_types: قائمة اختيارية من امتدادات الملفات للتصفية (مثل: ['.pdf', '.docx'])
        
    Returns:
        قائمة بنتائج التحميل
    """
    api_key = "YOUR_API_KEY"
    headers = {"x-api-key": api_key}
    
    # الحصول على قائمة الملفات في الدليل
    files = []
    for entry in os.scandir(folder_path):
        if entry.is_file():
            file_path = Path(entry.path)
            # تصفية حسب امتداد الملف إذا تم تحديده
            if file_types is None or file_path.suffix.lower() in file_types:
                files.append(file_path)
    
    print(f"تم العثور على {len(files)} ملف لتحميله")
    results = []
    
    # معالجة الملفات على دفعات
    for i in range(0, len(files), batch_size):
        batch = files[i:i+batch_size]
        print(f"معالجة الدفعة {i//batch_size + 1}/{(len(files) + batch_size - 1)//batch_size}: {len(batch)} ملفات")
        
        # تحميل الدفعة
        upload_files = []
        for file_path in batch:
            upload_files.append(('files', (file_path.name, open(file_path, 'rb'))))
        
        try:
            response = requests.post(
                f"https://api.rememberizer.ai/api/v1/vector-stores/{vector_store_id}/documents/upload",
                headers=headers,
                files=upload_files
            )
            
            # إغلاق جميع مقبضات الملفات
            for _, (_, file_obj) in upload_files:
                file_obj.close()
            
            if response.status_code in (200, 201, 207):
                batch_result = response.json()
                results.append(batch_result)
                print(f"تم تحميل الدفعة بنجاح - {len(batch_result.get('documents', []))} مستندات تمت معالجتها")
                
                # التحقق من الأخطاء
                if batch_result.get('errors') and len(batch_result['errors']) > 0:
                    print(f"تم مواجهة أخطاء: {len(batch_result['errors'])}")
                    for error in batch_result['errors']:
                        print(f"- {error['file']}: {error['error']}")
            else:
                print(f"فشل تحميل الدفعة برمز الحالة {response.status_code}: {response.text}")
                results.append({"error": f"فشل الدفعة: {response.text}"})
                
        except Exception as e:
            print(f"استثناء أثناء تحميل الدفعة: {str(e)}")
            results.append({"error": str(e)})
            
            # إغلاق أي مقبضات ملفات متبقية في حالة حدوث استثناء
            for _, (_, file_obj) in upload_files:
                try:
                    file_obj.close()
                except:
                    pass
        
        # تحديد معدل - توقف بين الدفعات
        if i + batch_size < len(files):
            print("توقف قبل الدفعة التالية...")
            time.sleep(2)
    
    return results

# مثال للاستخدام
results = batch_upload_to_vector_store(
    'vs_abc123',
    '/path/to/documents/folder',
    batch_size=5,
    file_types=['.pdf', '.docx', '.txt']
)

JavaScript

/**
 * رفع الملفات إلى متجر المتجهات على دفعات
 * 
 * @param {string} vectorStoreId - معرف متجر المتجهات
 * @param {FileList|File[]} files - الملفات المراد رفعها
 * @param {Object} options - خيارات التكوين
 * @returns {Promise<Array>} - قائمة بنتائج الرفع
 */
async function batchUploadToVectorStore(vectorStoreId, files, options = {}) {
  const {
    batchSize = 5,
    delayBetweenBatches = 2000,
    onProgress = null
  } = options;
  
  const apiKey = 'YOUR_API_KEY';
  const results = [];
  const fileList = Array.from(files);
  const totalBatches = Math.ceil(fileList.length / batchSize);
  
  console.log(`التحضير لرفع ${fileList.length} ملف في ${totalBatches} دفعات`);
  
  // معالجة الملفات على دفعات
  for (let i = 0; i < fileList.length; i += batchSize) {
    const batch = fileList.slice(i, i + batchSize);
    const batchNumber = Math.floor(i / batchSize) + 1;
    
    console.log(`معالجة الدفعة ${batchNumber}/${totalBatches}: ${batch.length} ملفات`);
    
    if (onProgress) {
      onProgress({
        currentBatch: batchNumber,
        totalBatches: totalBatches,
        filesInBatch: batch.length,
        totalFiles: fileList.length,
        completedFiles: i
      });
    }
    
    // إنشاء FormData لهذه الدفعة
    const formData = new FormData();
    batch.forEach(file => {
      formData.append('files', file);
    });
    
    try {
      const response = await fetch(
        `https://api.rememberizer.ai/api/v1/vector-stores/${vectorStoreId}/documents/upload`,
        {
          method: 'POST',
          headers: {
            'x-api-key': apiKey
          },
          body: formData
        }
      );
      
      if (response.ok) {
        const batchResult = await response.json();
        results.push(batchResult);
        
        console.log(`تم رفع الدفعة بنجاح - ${batchResult.documents?.length || 0} مستندات تمت معالجتها`);
        
        // التحقق من الأخطاء
        if (batchResult.errors && batchResult.errors.length > 0) {
          console.warn(`تمت مواجهة أخطاء: ${batchResult.errors.length}`);
          batchResult.errors.forEach(error => {
            console.warn(`- ${error.file}: ${error.error}`);
          });
        }
      } else {
        console.error(`فشل رفع الدفعة مع الحالة ${response.status}: ${await response.text()}`);
        results.push({ error: `فشلت الدفعة مع الحالة: ${response.status}` });
      }
    } catch (error) {
      console.error(`استثناء أثناء رفع الدفعة: ${error.message}`);
      results.push({ error: error.message });
    }
    
    // إضافة تأخير بين الدفعات لتجنب تحديد المعدل
    if (i + batchSize < fileList.length) {
      console.log(`توقف لمدة ${delayBetweenBatches}ms قبل الدفعة التالية...`);
      await new Promise(resolve => setTimeout(resolve, delayBetweenBatches));
    }
  }
  
  console.log(`اكتمل الرفع. تمت معالجة ${fileList.length} ملفات.`);
  return results;
}

// مثال للاستخدام مع عنصر إدخال الملفات
document.getElementById('upload-button').addEventListener('click', async () => {
  const fileInput = document.getElementById('file-input');
  const vectorStoreId = 'vs_abc123';
  
  const progressBar = document.getElementById('progress-bar');
  
  try {
    const results = await batchUploadToVectorStore(vectorStoreId, fileInput.files, {
      batchSize: 5,
      onProgress: (progress) => {
        // تحديث واجهة المستخدم للتقدم
        const percentage = Math.round((progress.completedFiles / progress.totalFiles) * 100);
        progressBar.style.width = `${percentage}%`;
        progressBar.textContent = `${percentage}% (دفعة ${progress.currentBatch}/${progress.totalBatches})`;
      }
    });
    
    console.log('نتائج الرفع المكتملة:', results);
  } catch (error) {
    console.error('فشل الرفع:', error);
  }
});

Ruby

require 'net/http'
require 'uri'
require 'json'
require 'mime/types'

# رفع الملفات إلى متجر المتجهات على دفعات
#
# @param vector_store_id [String] معرف متجر المتجهات
# @param folder_path [String] مسار المجلد الذي يحتوي على الملفات المراد تحميلها
# @param batch_size [Integer] عدد الملفات التي سيتم تحميلها في كل دفعة
# @param file_types [Array<String>] مصفوفة اختيارية من امتدادات الملفات للتصفية بواسطة
# @param delay_between_batches [Float] ثوانٍ للانتظار بين الدفعات
# @return [Array] قائمة نتائج التحميل
def batch_upload_to_vector_store(vector_store_id, folder_path, batch_size: 5, file_types: nil, delay_between_batches: 2.0)
  api_key = 'YOUR_API_KEY'
  results = []
  
  # الحصول على قائمة الملفات في الدليل
  files = Dir.entries(folder_path)
    .select { |f| File.file?(File.join(folder_path, f)) }
    .select { |f| file_types.nil? || file_types.include?(File.extname(f).downcase) }
    .map { |f| File.join(folder_path, f) }
  
  puts "تم العثور على #{files.count} ملفات لتحميلها"
  total_batches = (files.count.to_f / batch_size).ceil
  
  # معالجة الملفات على دفعات
  files.each_slice(batch_size).with_index do |batch, batch_index|
    puts "معالجة الدفعة #{batch_index + 1}/#{total_batches}: #{batch.count} ملفات"
    
    # إعداد طلب HTTP
    uri = URI("https://api.rememberizer.ai/api/v1/vector-stores/#{vector_store_id}/documents/upload")
    request = Net::HTTP::Post.new(uri)
    request['x-api-key'] = api_key
    
    # إنشاء حد للفورم المتعدد الأجزاء
    boundary = "RubyBoundary#{rand(1000000)}"
    request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
    
    # بناء جسم الطلب
    body = []
    batch.each do |file_path|
      file_name = File.basename(file_path)
      mime_type = MIME::Types.type_for(file_path).first&.content_type || 'application/octet-stream'
      
      begin
        file_content = File.binread(file_path)
        
        body << "--#{boundary}\r\n"
        body << "Content-Disposition: form-data; name=\"files\"; filename=\"#{file_name}\"\r\n"
        body << "Content-Type: #{mime_type}\r\n\r\n"
        body << file_content
        body << "\r\n"
      rescue => e
        puts "خطأ في قراءة الملف #{file_path}: #{e.message}"
      end
    end
    body << "--#{boundary}--\r\n"
    
    request.body = body.join
    
    # إرسال الطلب
    begin
      http = Net::HTTP.new(uri.host, uri.port)
      http.use_ssl = true
      response = http.request(request)
      
      if response.code.to_i == 200 || response.code.to_i == 201 || response.code.to_i == 207
        batch_result = JSON.parse(response.body)
        results << batch_result
        
        puts "تم تحميل الدفعة بنجاح - #{batch_result['documents']&.count || 0} مستندات تمت معالجتها"
        
        # التحقق من الأخطاء
        if batch_result['errors'] && !batch_result['errors'].empty?
          puts "الأخطاء التي تم مواجهتها: #{batch_result['errors'].count}"
          batch_result['errors'].each do |error|
            puts "- #{error['file']}: #{error['error']}"
          end
        end
      else
        puts "فشل تحميل الدفعة مع رمز الحالة #{response.code}: #{response.body}"
        results << { "error" => "فشل الدفعة: #{response.body}" }
      end
    rescue => e
      puts "استثناء أثناء تحميل الدفعة: #{e.message}"
      results << { "error" => e.message }
    end
    
    # تحديد معدل التحميل - توقف بين الدفعات
    if batch_index < total_batches - 1
      puts "توقف لمدة #{delay_between_batches} ثوانٍ قبل الدفعة التالية..."
      sleep(delay_between_batches)
    end
  end
  
  puts "اكتمل التحميل. تمت معالجة #{files.count} ملفات."
  results
end

# مثال على الاستخدام
results = batch_upload_to_vector_store(
  'vs_abc123',
  '/path/to/documents/folder',
  batch_size: 5,
  file_types: ['.pdf', '.docx', '.txt'],
  delay_between_batches: 2.0
)

أفضل الممارسات لتحميل الدفعات

لتحسين الأداء والموثوقية عند تحميل كميات كبيرة من الملفات:

1. إدارة حجم الدفعة: احتفظ بأحجام الدفعات بين 5-10 ملفات لتحقيق الأداء الأمثل. عدد كبير جداً من الملفات في طلب واحد يزيد من خطر حدوث مهلات.

2. تنفيذ تحديد المعدل: أضف تأخيرات بين الدفعات (يوصى بـ 2-3 ثواني) لتجنب الوصول إلى حدود معدل API.

3. إضافة منطق إعادة المحاولة عند الخطأ: بالنسبة للأنظمة الإنتاجية، نفذ منطق إعادة المحاولة للتحميلات الفاشلة مع زيادة زمن الانتظار بشكل أسي.

4. التحقق من أنواع الملفات: قم بفرز الملفات مسبقاً لضمان أنها من الأنواع المدعومة قبل محاولة التحميل.

5. مراقبة تقدم الدفعة: بالنسبة للتطبيقات الموجهة للمستخدمين، قدم ملاحظات حول تقدم العمليات الخاصة بالدفعات.

6. التعامل مع النجاح الجزئي: قد يعيد API رمز الحالة 207 للنجاح الجزئي. تحقق دائماً من حالات الوثائق الفردية.

7. تنظيف الموارد: تأكد من إغلاق جميع مقبضات الملفات بشكل صحيح، خاصة عند حدوث أخطاء.

8. التوازي بحكمة: بالنسبة للتحميلات الكبيرة جداً (آلاف الملفات)، اعتبر استخدام عمليات دفعات متزامنة متعددة تستهدف متاجر متجهات مختلفة، ثم اجمع النتائج لاحقاً إذا لزم الأمر.

9. تنفيذ المجموعات الاختبارية: بالنسبة للبيانات الحرجة، تحقق من سلامة الملفات قبل وبعد التحميل باستخدام المجموعات الاختبارية.

10. تسجيل النتائج بشكل شامل: احتفظ بسجلات مفصلة لجميع عمليات التحميل لتسهيل استكشاف الأخطاء.

من خلال اتباع هذه الممارسات الجيدة، يمكنك إدارة إدخال الوثائق على نطاق واسع بكفاءة في متاجر المتجهات الخاصة بك.