Unggah beberapa dokumen sekaligus - OpenSearch

OpenSearch LLM-Based Conversational Search Edition memungkinkan Anda memanggil API untuk mengunggah beberapa dokumen secara bersamaan.

Prasyarat

Kunci API untuk otentikasi identitas telah diperoleh. Saat memanggil operasi API OpenSearch LLM-Based Conversational Search Edition, Anda harus diautentikasi. Untuk informasi lebih lanjut, lihat Kelola Kunci API. LLM adalah singkatan dari model bahasa besar.
Titik akhir telah diperoleh. Saat memanggil operasi API OpenSearch LLM-Based Conversational Search Edition, Anda harus menentukan titik akhir. Untuk informasi lebih lanjut, lihat Memperoleh Titik Akhir.

Informasi operasi

Metode permintaan	Protokol permintaan	Format data permintaan
POST	HTTP	JSON

URL Permintaan

{host}/v3/openapi/apps/[app_group_identity]/actions/knowledge-bulk

{host}: Titik akhir yang digunakan untuk memanggil operasi API. Anda dapat memanggil operasi API melalui Internet atau virtual private cloud (VPC). Untuk informasi lebih lanjut tentang cara memperoleh titik akhir, lihat Memperoleh Titik Akhir.
{app_group_identity}: Nama aplikasi yang ingin Anda akses. Anda dapat masuk ke Konsol OpenSearch LLM-Based Conversational Search Edition dan melihat nama aplikasi instance yang sesuai di halaman Manajemen Instance.

Parameter permintaan

Parameter Header

Parameter	Tipe	Diperlukan	Deskripsi	Contoh
Content-Type	string	Ya	Format data permintaan. Hanya format JSON yang didukung. Atur nilainya menjadi application/json.	application/json
Authorization	string	Ya	Kunci API yang digunakan untuk otentikasi permintaan. Nilai harus dimulai dengan Bearer.	Bearer OS-d1**2a

Parameter Body

Parameter	Tipe	Diperlukan	Deskripsi	Contoh
cmd	string	Ya	Operasi yang akan dilakukan pada dokumen.	ADD/DELETE
fields	map	Ya	Kumpulan bidang.
fields.id	string	Ya	ID kunci utama.	13579
fields.title	string	Tidak	Judul dokumen.	Something interesting
fields.url	string	Tidak	URL dokumen.	https://www.aliyun.com
fields.content	string	Ya	Isi dokumen.	No, is not.

Contoh badan permintaan

1. Unggah dokumen ke tabel utama

['{
    "cmd": "ADD",
    "fields": {
      "id": "13579",
      "title": "Something interesting",
      "url": "https://www.aliyun.com",
      "content": "No, is not."
      }
}']

Unggah dokumen tidak terstruktur seperti file PDF, DOC, TXT, atau HTML

['{
    "cmd" : "URL/BASE64",
    "fields": {
      "id": "Opsional. ID dokumen.",
      "type": "Opsional. Jenis file seperti PDF, DOC, TXT, atau HTML.",
      "title": "Opsional. Nama file.",
      "content": "Data yang dikodekan dalam URL/Base64.",
      "url": "Opsional. URL file."
    }
 }']

Catatan

Parameter url hanya mendukung URL yang dihasilkan untuk objek Object Storage Service (OSS) dengan memanggil metode generatePresignedUrl pada klien OSS.

2. Unggah dokumen ke tabel kustom

['{
    "cmd" : "ADD",
    "fields": {					# Bidang. Tentukan bidang berdasarkan skema tabel kustom.
      "key1": "value1",
      "key2": "value2",
      "key3": "value3"
    },
    "table_name": "Nama tabel kustom."	# Nama tabel. Jika parameter ini dibiarkan kosong, operasi dilakukan pada tabel utama.
  }']

3. Hapus tabel

['{
    "cmd" : "DELETE",
    "fields": {
      "id": "13579333"
    }
}']

cmd: Diperlukan. Operasi yang akan dilakukan pada dokumen. Nilai valid: ADD dan DELETE. Kami merekomendasikan agar Anda mengirim permintaan untuk melakukan operasi pada beberapa dokumen sekaligus. Ini meningkatkan efisiensi interaksi jaringan dan efisiensi pemrosesan. Nilai ADD menentukan bahwa dokumen akan dibuat. Jika dokumen dengan nilai kunci utama yang ditentukan ada, dokumen asli dihapus sebelum dokumen baru dibuat. Nilai DELETE menentukan bahwa dokumen akan dihapus. Jika tidak ada dokumen dengan nilai kunci utama yang ditentukan, operasi dianggap berhasil.
fields: Diperlukan. Bidang tempat operasi akan dilakukan di dokumen. Anda harus menentukan bidang kunci utama. OpenSearch mengidentifikasi dokumen berdasarkan nilai kunci utamanya. Jika Anda ingin menghapus dokumen, Anda hanya perlu menentukan bidang kunci utama dokumen tersebut.
Pada kode contoh sebelumnya, lapisan terluar adalah array JSON yang digunakan untuk mengelola beberapa dokumen sekaligus.

Parameter respons

Parameter	Tipe	Deskripsi
errors	list	Pesan kesalahan.
status	string	Hasil eksekusi permintaan. Nilai valid: OK dan FAIL. Nilai OK menunjukkan bahwa permintaan berhasil. Nilai FAIL menunjukkan bahwa permintaan gagal. Dalam hal ini, periksa kesalahan berdasarkan kode kesalahan.
request_id	string	ID permintaan.
result	boolean	Hasil permintaan. Nilai true dikembalikan jika permintaan berhasil. Parameter ini tidak dikembalikan jika permintaan gagal.
total	int	Jumlah total dokumen yang diunggah.
success	int	Jumlah total dokumen yang berhasil diunggah.
failure	int	Jumlah total dokumen yang gagal diunggah.
failed_ids	array	ID dokumen yang gagal diunggah.

Contoh badan respons

{
  "request_id" : "abc123-ABC",
  "result" : {
    "total": 100,
    "success": 50,
    "failure": 50,
    "failed_ids": [
      "id1",
      "id2",
      "id3",
      "..."
    ]
  }
  "errors" : [
    {
      "code" : "Kode kesalahan yang dikembalikan jika terjadi kesalahan.",
      "message" : "Pesan kesalahan yang dikembalikan jika terjadi kesalahan."
    }
  ]
}

Perhatian

Saat mendorong data dengan memanggil API atau menggunakan SDK OpenSearch, nama bidang aplikasi tidak peka huruf besar-kecil.
Anda dapat mendorong data sejumlah kali dan ukuran terbatas dengan memanggil API atau menggunakan SDK OpenSearch. Batasan berbeda diberlakukan pada aplikasi yang berbeda. Untuk informasi lebih lanjut, lihat Batasan.
Setelah data diunggah, pastikan Anda memeriksa nilai pengembalian. Jika kode kesalahan dikembalikan, terutama 3007, periksa kesalahan berdasarkan kode kesalahan dan coba lagi. Jika tidak, kehilangan data mungkin terjadi. OpenSearch memproses data secara asinkron. Nilai pengembalian OK menunjukkan bahwa OpenSearch menerima data. Ini tidak menunjukkan bahwa data diproses dengan benar. Jika terjadi kesalahan selama pemrosesan data, pesan kesalahan terkait ditampilkan di konsol OpenSearch. Periksa pesan kesalahan sesegera mungkin.
Anda hanya dapat mengunggah ukuran data terbatas saat mengirim permintaan HTTP POST. Jika ukuran data sebelum pengkodean melebihi 2 MB, OpenSearch menolak permintaan dan mengembalikan kesalahan.
Jika body permintaan HTTP POST untuk mendorong data berisi karakter Cina, Anda harus mengkodekan body dalam UTF-8. Selain itu, nilai header Content-MD5 juga harus dikodekan dalam UTF-8 sebelum nilai MD5 dihitung. Jika tidak, kesalahan dikembalikan dan permintaan gagal.
Jika kode kesalahan 4016 dikembalikan, pengguna RAM yang Anda gunakan untuk memanggil API tidak memiliki izin yang diperlukan. Dalam hal ini, Anda perlu melampirkan kebijakan AliyunOpenSearchFullAccess ke pengguna RAM. Untuk informasi lebih lanjut, lihat Memberikan Izin kepada Pengguna RAM.