Gunakan SearchKnowledge untuk menjawab pertanyaan berbasis teks - OpenSearch

Fitur Tanya Jawab Berbasis Teks (Text Q&A) menjawab kueri dengan mengambil konten dari basis pengetahuan. Fitur ini menggunakan ID sesi untuk mempertahankan konteks dalam percakapan multi-putaran. Anda juga dapat memilih Large Language Model (LLM) yang berbeda untuk menghasilkan jawaban dan menyesuaikan respons.

Prasyarat

Dapatkan Kunci API untuk mengotentikasi panggilan ke OpenSearch - Edisi LLM Intelligent Q&A. Untuk informasi lebih lanjut, lihat Kelola Kunci API.
Dapatkan titik akhir layanan untuk melakukan panggilan ke OpenSearch - Edisi LLM Intelligent Q&A. Untuk informasi lebih lanjut, lihat Dapatkan titik akhir layanan.

Penting

API ini dirancang untuk penggunaan di sisi server dan tidak boleh dipanggil langsung dari lingkungan front-end seperti browser, mini program, atau aplikasi seluler. Ada dua alasan untuk hal ini. Pertama, API menggunakan header Authorization: Bearer <API key> untuk otentikasi. Kunci API merupakan kredensial jangka panjang; menyematkannya dalam kode front-end akan membuatnya rentan terhadap pencurian. Kedua, API ini tidak mendukung Cross-Origin Resource Sharing (CORS), sehingga browser akan memblokir semua panggilan langsung. Anda harus menyimpan kunci API di server Anda, lakukan panggilan dari server, lalu kembalikan hasilnya ke front-end.

API

Metode permintaan	Protokol	Format permintaan
POST	HTTP	JSON

URL Permintaan

{host}/v3/openapi/apps/{app_group_identity}/actions/knowledge-search

{host}: Titik akhir layanan, dapat diakses melalui Internet atau virtual private cloud (VPC). Untuk informasi lebih lanjut, lihat Dapatkan titik akhir.
{app_group_identity}: Nama aplikasi. Masuk ke Konsol OpenSearch Edisi Pencarian Percakapan Berbasis LLM dan temukan nama ini di halaman Manajemen Instans.

Parameter permintaan

Parameter header

Parameter	Tipe	Wajib	Deskripsi	Contoh
Content-Type	string	Ya	Menentukan jenis media dari badan permintaan. Harus bernilai "application/json".	application/json
Authorization	string	Ya	Kunci API Anda, diawali dengan "Bearer ".	Bearer OS-d1**2a
accept	string	Tidak	Atur ke "text/event-stream" untuk menerima respons streaming menggunakan Server-Sent Events (SSE).	text/event-stream

Parameter badan

Parameter	Tipe	Wajib	Deskripsi	Nilai contoh
question	map	Ya	Pertanyaan input.	{ "text":"user question", "type": "TEXT", "session" : "" }
question.text	string	Ya	Konten teks dari pertanyaan pengguna.	user question
question.session	string	Tidak	ID sesi yang mengidentifikasi konteks percakapan multi-putaran. Nilai yang valid: Jika parameter ini tidak diatur atau dibiarkan kosong, percakapan multi-putaran dinonaktifkan. Jika Anda memberikan nilai yang tidak kosong, percakapan multi-putaran diaktifkan. Sistem menyimpan percakapan dengan ID sesi yang sama untuk konteks. Riwayat percakapan disimpan hingga 7 hari. Gunakan parameter `history_max` untuk menentukan jumlah putaran percakapan yang disimpan (maksimal 20).	1725530408586
question.type	string	Tidak	Jenis pertanyaan input. Atur nilai ini ke `TEXT`.	TEXT
options	map	Tidak	Parameter opsional untuk mengontrol pengaturan seperti pengambilan, pemilihan model, dan prompt.
options.chat	map	Tidak	Parameter untuk mengakses Large Language Model (LLM).
options.chat.disable	boolean	Tidak	Menentukan apakah akses ke LLM dinonaktifkan. `false`: Mengakses LLM untuk merangkum dan menghasilkan hasil. Ini adalah nilai default. `true`: Tidak mengakses LLM.	false
options.chat.stream	boolean	Tidak	Menentukan apakah respons streaming diaktifkan. `true`: Mengaktifkan respons streaming. Ini adalah nilai default. `false`: Menonaktifkan respons streaming.	true
options.chat.model	string	Tidak	Large Language Model (LLM) yang digunakan. Nilai yang valid: Asia Pasifik SE 1 (Singapura) opensearch-llama2-13b opensearch-falcon-7b qwen-turbo qwen-plus qwen-max qwen2-72b-instruct	opensearch-llama2-13b
options.chat.enable_deep_search	boolean	Tidak	Menentukan apakah deep search diaktifkan. `true`: Mengaktifkan deep search. Fitur ini menggunakan penalaran multi-putaran untuk mensintesis data guna menghasilkan respons akhir, yang dapat meningkatkan waktu dan sumber daya komputasi yang digunakan per putaran percakapan. `false`: Menonaktifkan deep search.	false
options.chat.model_generation	integer	Tidak	Menentukan versi model yang digunakan untuk model produk kustom. Jika Anda tidak menentukan parameter ini, sistem menggunakan versi tertua secara default.	20
options.chat.prompt_template	string	Tidak	Nama templat prompt kustom. Jika parameter ini kosong, sistem menggunakan templat prompt bawaannya secara default.	user_defined_prompt_name
options.chat.prompt_config	object	Tidak	Pasangan kunci-nilai untuk mengonfigurasi prompt kustom. Parameter harus dalam format berikut: `{ "String_key": "value", "Integer_key" : 1 }`	`{ "attitude": "normal", "rule" : "detailed", "noanswer": "sorry", "language": "Chinese", "role": false, "role_name": "AI Assistant", }`
options.chat.prompt_config.attitude	string	Tidak	Parameter untuk templat prompt bawaan yang mengontrol nada respons. Nilai default adalah `normal`. `normal`: Nada netral. `polite`: Nada ramah dan sopan. `patience`: Nada bijaksana dan sabar.	normal
options.chat.prompt_config.rule	string	Tidak	Mengontrol tingkat detail dalam respons. Nilai default adalah `detailed`. `detailed`: Rinci dan profesional. `stepbystep`: Detail dan langkah demi langkah.	detailed
options.chat.prompt_config.noanswer	string	Tidak	Respons yang dikembalikan ketika sistem tidak dapat menjawab pertanyaan. Nilai default adalah `sorry`. `sorry`: "Maaf, saya tidak dapat menjawab pertanyaan ini berdasarkan informasi yang tersedia." `uncertain`: "Saya tidak tahu."	sorry
options.chat.prompt_config.language	string	Tidak	Bahasa yang digunakan untuk respons. Nilai default adalah `Chinese`. `Chinese`: Bahasa Mandarin. `English`: Bahasa Inggris. `Thai`: Bahasa Thailand. `Korean`: Bahasa Korea.	Chinese
options.chat.prompt_config.role	boolean	Tidak	Menentukan apakah persona kustom untuk respons diaktifkan. Jika Anda mengatur nilai ini ke `true`, sistem menghasilkan respons berdasarkan persona yang ditentukan dalam `role_name`.	false
options.chat.prompt_config.role_name	string	Tidak	Nama persona kustom. Contohnya: AI Assistant.	AI Assistant
options.chat.prompt_config.out_format	string	Tidak	Format konten output. Nilai default adalah `text`. `text`: Teks. `table`: Tabel. `list`: Daftar. `markdown`: Markdown.	text
options.chat.generate_config.repetition_penalty	float	Tidak	Mengontrol penalti untuk pengulangan dalam urutan token yang dihasilkan. Nilai yang lebih tinggi mengurangi kemungkinan pengulangan. Nilai `1.0` menunjukkan tidak ada penalti. Tidak ada rentang nilai yang ketat.	1.01
options.chat.generate_config.top_k	integer	Tidak	Jumlah token dengan probabilitas tertinggi yang dipertimbangkan untuk pengambilan sampel. Misalnya, nilai `50` menginstruksikan model untuk mengambil sampel hanya dari 50 token dengan skor tertinggi. Nilai yang lebih tinggi meningkatkan keacakan, sedangkan nilai yang lebih rendah meningkatkan determinisme. Nilai default adalah `0`, yang menonaktifkan strategi top-k dan mengandalkan strategi top-p sebagai gantinya.	50
options.chat.generate_config.top_p	float	Tidak	Ambang batas probabilitas kumulatif untuk pengambilan sampel inti. Misalnya, nilai `0.8` berarti model memilih dari himpunan token terkecil yang probabilitas kumulatifnya minimal 0.8. Nilai yang valid berada dalam rentang (0, 1.0). Nilai yang lebih tinggi meningkatkan keacakan, sedangkan nilai yang lebih rendah meningkatkan determinisme.	0.5
options.chat.generate_config.temperature	float	Tidak	Mengontrol keacakan dan keragaman teks yang dihasilkan. Suhu yang lebih tinggi meratakan distribusi probabilitas token kandidat, memungkinkan model memilih token yang kurang mungkin dan membuat output lebih beragam. Nilai yang lebih rendah memperjelas distribusi, membuat model lebih cenderung memilih token berprobabilitas tinggi dan output menjadi lebih deterministik. Rentang nilai: [0, 2). Jangan atur parameter ini ke 0. versi python >=1.10.1 versi java >= 2.5.1	0.7
options.chat.history_max	integer	Tidak	Jumlah maksimum putaran yang disimpan dalam riwayat percakapan multi-putaran. Nilai maksimum adalah 20. Nilai default adalah 1.	20
options.chat.link	boolean	Tidak	Menentukan apakah kutipan sumber disertakan dalam respons. Nilai yang valid: `true`: Respons menyertakan kutipan sumber. `false`: Respons tidak menyertakan kutipan sumber. Ini adalah nilai default. Berikut adalah contoh respons yang berisi kutipan: Anda dapat memperluas kapasitas disk ECS secara online maupun offline[^1^]. Ekspansi online tidak memerlukan restart instans, sedangkan ekspansi offline memerlukannya[^1^]. Untuk melakukan ekspansi, buka Konsol ECS, pilih disk tersebut, lalu pilih Expand Disk dari kolom Actions. Kemudian, pilih metode ekspansi sesuai kebutuhan[^1^]. Jika Anda perlu memperluas partisi dan sistem file, Anda dapat melakukannya dari konsol[^2^]. Setelah kapasitas disk diperluas, kapasitas tersebut tidak dapat dikurangi, jadi rencanakan storage space Anda dengan cermat[^3^]. Angka yang diapit oleh `[^` dan `^]` berkorespondensi dengan dokumen dalam objek `reference` pada respons API. Misalnya, `[^1^]` merujuk ke dokumen pertama dalam objek `reference`.	false
options.chat.rich_text_strategy	string	Tidak	Strategi post-processing untuk output dari LLM rich-text. Jika parameter ini kosong atau tidak ditentukan, pemrosesan rich text dinonaktifkan secara default. `inside_response`: Merender tag rich text langsung dalam konten respons dalam format Markdown. Tabel dimasukkan sebagai HTML dalam Markdown. `extend_response`: Jika respons berisi tag rich text, konten untuk setiap tag dikembalikan secara terpisah dalam objek rich_text_ref. Misalnya, konten gambar dikembalikan sebagai URL, konten tabel sebagai HTML, dan konten kode sebagai teks biasa.	inside_response
options.chat.agent	map	Tidak	Menentukan opsi untuk kemampuan penggunaan tool Agen RAG. Saat diaktifkan, model memutuskan apakah akan mengeksekusi tool berdasarkan konten yang tersedia. LLM yang saat ini mendukung fitur ini adalah: qwen-plus qwen-max qwen2-72b-instruct
options.chat.agent.think_process	boolean	Tidak	Menentukan apakah proses berpikir agen dikembalikan.	true
options.chat.agent.max_think_round	integer	Tidak	Jumlah maksimum putaran berpikir untuk agen. Nilainya tidak boleh melebihi 20.	10
options.chat.agent.language	string	Tidak	Bahasa untuk proses berpikir dan jawaban akhir. `AUTO`: Secara otomatis menentukan apakah menggunakan bahasa Mandarin atau Inggris berdasarkan kueri pengguna. `CN`: Bahasa Mandarin. `EN`: Bahasa Inggris.	AUTO
options.chat.agent.tools	list of string	Tidak	Tool RAG yang dapat digunakan agen. Tool berikut tersedia: `knowledge_search`: Melakukan pengambilan dari basis pengetahuan.	["knowledge_search"]
options.retrieve	map	Tidak	Menentukan parameter yang mengontrol proses pengambilan.
options.retrieve.web_search.enable	boolean	Tidak	Menentukan apakah pencarian web diaktifkan. `true`: Mengaktifkan pencarian web. Sistem menghasilkan respons berdasarkan data dari pencarian web, yang dapat meningkatkan waktu dan konsumsi sumber daya. `false`: Menonaktifkan pencarian web. Ini adalah nilai default.	false
doc	map	Tidak	Menentukan parameter terkait pengambilan dokumen.
options.retrieve.doc.disable	boolean	Tidak	Menentukan apakah pengambilan dari basis pengetahuan dinonaktifkan. `false`: Mengaktifkan pengambilan. Ini adalah nilai default. `true`: Menonaktifkan pengambilan.	false
options.retrieve.doc.filter	string	Tidak	Ekspresi filter untuk memilih data yang akan diambil dari basis pengetahuan. Jika tidak ditentukan, tidak ada filter yang diterapkan. Untuk contoh sintaksis, lihat parameter filter. Bidang yang didukung: `table`: Tabel tempat dokumen disimpan. `raw_pk`: Kunci primer dokumen. `category`: Kategori dokumen. `score`: Skor dokumen. `timestamp`: Timestamp dokumen. Format contoh: `"filter" : "raw_pk=\"123\"" # Mengambil data hanya dari dokumen dengan ID 123. "filter" : "category=\"value1\"" # Mengambil data hanya dari dokumen dalam kategori "value1". "filter" : "category=\"value1\" OR category=\"value2\"" # Mengambil data dari dokumen dalam kategori "value1" dan "value2". "filter" : "score>1.0" # Mengambil data hanya dari dokumen dengan skor lebih besar dari 1.0. "filter" : "timestamp>1356969600" # Mengambil data hanya dari dokumen dengan timestamp setelah 2013-01-01.`	category=\"value1\"
options.retrieve.doc.sf	float	Tidak	Ambang batas skor untuk pengambilan berbasis vektor. Saat vektor jarang dinonaktifkan: Rentang nilai adalah `[0, 2.0]`, dan nilai default adalah `1.3`. Nilai yang lebih rendah menghasilkan hasil yang lebih relevan tetapi lebih sedikit. Nilai yang lebih tinggi dapat mengambil hasil yang kurang relevan. Saat vektor jarang diaktifkan: Nilai default adalah `0.35`. Nilai yang lebih tinggi menghasilkan hasil yang lebih relevan tetapi lebih sedikit. Nilai yang lebih rendah dapat mengambil hasil yang kurang relevan.	0.35
options.retrieve.doc.top_n	integer	Tidak	Jumlah dokumen yang diambil. Nilainya harus berada dalam rentang (0, 50]. Nilai default adalah 5.	5
options.retrieve.doc.formula	string	Tidak	Rumus peringkat kustom untuk dokumen yang diambil. Catatan Untuk detail sintaksis, lihat Fungsi Pengurutan Bisnis. Fitur Relevansi Algoritmik dan Relevansi Geografis tidak didukung.	-timestamp: Mengurutkan dokumen secara menurun berdasarkan bidang timestamp.
options.retrieve.doc.rerank_size	integer	Tidak	Jumlah dokumen yang disusun ulang saat fitur penyusunan ulang diaktifkan. Nilainya harus berada dalam rentang (0, 100]. Nilai default adalah 30.	30
options.retrieve.doc.operator	string	Tidak	Hubungan antar istilah yang dihasilkan dari tokenisasi `question.text` untuk pengambilan basis pengetahuan. Parameter ini hanya berlaku saat Anda menonaktifkan vektor jarang. `AND`: Semua istilah harus muncul dalam dokumen agar dokumen tersebut diambil. Ini adalah nilai default. `OR`: Minimal satu istilah harus muncul dalam dokumen agar dokumen tersebut diambil.	AND
options.retrieve.doc.dense_weight	float	Tidak	Saat vektor jarang diaktifkan, parameter ini mengontrol bobot vektor padat selama pengambilan dokumen. Nilainya harus berada dalam rentang (0.0, 1.0). Nilai default adalah 0.7.	0.7
options.retrieve.entry	map	Tidak	Menentukan parameter untuk mengambil hasil dari data intervensi manual.
options.retrieve.entry.disable	boolean	Tidak	Menentukan apakah pengambilan dari data intervensi manual dinonaktifkan. `false`: Mengaktifkan pengambilan. Ini adalah nilai default. `true`: Menonaktifkan pengambilan.	false
options.retrieve.entry.sf	float	Tidak	Ambang batas skor vektor untuk mengambil data intervensi manual. Rentang nilai adalah `[0, 2.0]`, dan nilai default adalah `0.3`. Nilai yang lebih rendah mengambil hasil yang lebih sedikit tetapi lebih relevan, sedangkan nilai yang lebih tinggi dapat mengambil hasil yang kurang relevan.	0.3
options.retrieve.image	map	Tidak	Menentukan parameter untuk mengambil hasil gambar dari basis pengetahuan.
options.retrieve.image.disable	boolean	Tidak	Menentukan apakah pengambilan gambar dinonaktifkan. Nilai default adalah `false`. `false`: Mengaktifkan pengambilan gambar. Ini adalah nilai default. `true`: Menonaktifkan pengambilan gambar.	false
options.retrieve.image.sf	float	Tidak	Ambang batas skor untuk pengambilan vektor gambar. Saat vektor jarang dinonaktifkan: Rentang nilai adalah `[0, 2.0]`, dan nilai default adalah `1.0`. Nilai yang lebih rendah menghasilkan hasil yang lebih relevan tetapi lebih sedikit. Nilai yang lebih tinggi dapat mengambil hasil yang kurang relevan. Saat vektor jarang diaktifkan: Nilai default adalah `0.5`. Nilai yang lebih tinggi menghasilkan hasil yang lebih relevan tetapi lebih sedikit. Nilai yang lebih rendah dapat mengambil hasil yang kurang relevan.	1.0
options.retrieve.image.dense_weight	float	Tidak	Saat vektor jarang diaktifkan, parameter ini mengontrol bobot vektor padat selama pengambilan gambar. Nilainya harus berada dalam rentang (0.0, 1.0). Nilai default adalah 0.7.	0.7
options.retrieve.qp	map	Tidak	Menentukan opsi untuk penulisan ulang kueri.
options.retrieve.qp.query_extend	boolean	Tidak	Menentukan apakah kueri pengguna diperluas. Mesin pencari menggunakan kueri yang diperluas untuk mengambil chunk dokumen. `false`: Tidak memperluas kueri. Ini adalah nilai default. `true`: Memperluas kueri. Opsi ini memerlukan panggilan tambahan ke LLM, yang meningkatkan latensi respons. Jangan aktifkan opsi ini untuk aplikasi yang sensitif terhadap latensi.	false
options.retrieve.qp.query_extend_num	integer	Tidak	Saat perluasan kueri diaktifkan, parameter ini menentukan jumlah maksimum kueri tambahan yang dihasilkan. Nilai default adalah 5.	5
options.retrieve.rerank	map	Tidak	Menentukan opsi untuk penyusunan ulang dokumen yang diambil.
options.retrieve.rerank.enable	boolean	Tidak	Menentukan apakah model digunakan untuk menyusun ulang hasil pencarian berdasarkan relevansi. Nilai yang valid: `true`: Menyusun ulang hasil menggunakan model. `false`: Tidak menyusun ulang hasil. Default adalah `false` jika `options.retrieve.doc.formula` ditentukan; jika tidak, nilainya `true`.	true
options.retrieve.rerank.model	string	Tidak	Nama model besar yang digunakan untuk penyusunan ulang. `ops-bge-reranker-larger`: Model bge-reranker. Ini adalah nilai default. `ops-text-reranker-001`: Model reranker proprietary.	ops-bge-reranker-larger
options.retrieve.return_hits	boolean	Tidak	Menentukan apakah hasil pengambilan dokumen dikembalikan, yang berkorespondensi dengan objek `search_hits` dalam respons.	false

Badan permintaan

{
  "question": {
    "text": "What is Alibaba Cloud OpenSearch?",
    "session": "session_001",
    "type": "TEXT"
  },
  "options": {
    "chat": {
      "disable": false,
      "stream": false,
      "model": "Qwen",
      "history_max": 20,
      "link": false,
      "agent": {
        "tools": ["knowledge_search"]
      }
    },
    "retrieve": {
      "doc": {
        "disable": false,
        "filter": "category=\"type\"",
        "sf": 0.35,
        "top_n": 5,
        "operator": "OR"
      },
      "web_search": { "enable": false },
      "entry": { "disable": false, "sf": 0.3 },
      "image": { "disable": false, "sf": 1.0 },
      "rerank": {
        "enable": true,
        "model": "ops-bge-reranker-larger"
      },
      "return_hits": false
    }
  }
}

Parameter utama:

Gunakan question.session untuk mengaktifkan konteks percakapan multi-putaran.
Atur options.chat.disable ke true untuk melewati LLM dan mengembalikan hasil pengambilan.
Gunakan options.retrieve.doc.top_n untuk menentukan jumlah dokumen yang diambil. Nilai default adalah 5.
Atur options.retrieve.return_hits ke true untuk mengembalikan konten detail dari search_hits.

Parameter respons

Parameter	Tipe	Deskripsi
request_id	string	Identifikasi unik permintaan. Sertakan nilai ini dalam permintaan dukungan.
status	string	Status pemrosesan permintaan. `OK`: Permintaan berhasil. `FAIL`: Permintaan gagal.
latency	float	Waktu pemrosesan server dalam milidetik. Dikembalikan hanya saat permintaan berhasil.
id	integer	Kunci primer.
title	string	Judul dokumen.
category	string	Nama kategori.
url	string	URL dokumen.
answer	string	Jawaban yang dihasilkan.
type	string	Jenis hasil.
scores	array	Skor relevansi dokumen.
event	string	Jenis event streaming. Satu putaran berpikir mencakup event `THINK`, `ACTION`, dan `ANSWER`, meskipun `THINK` bersifat opsional. Event-event ini menunjukkan proses berpikir model (`THINK`), aksi yang dilakukan (`ACTION`), dan kesimpulan putaran saat ini (`ANSWER`). `SUMMARY` memberikan jawaban akhir dan hanya dikembalikan sekali.
event_status	string	Menunjukkan apakah event telah selesai. `PROCESSING`: Event sedang berlangsung. `FINISHED`: Event telah selesai.
code	string	Kode kesalahan. Dikembalikan hanya saat terjadi kesalahan.
message	string	Pesan kesalahan. Dikembalikan hanya saat terjadi kesalahan.

Contoh badan respons

Respons berhasil

{
  "request_id": "6859E98D-D885-4AEF-B61C-9683A0184744",
  "status": "OK",
  "latency": 6684.41,
  "result": {
    "data": [
      {
        "answer": "Alibaba Cloud OpenSearch adalah layanan terkelola untuk mencari data terstruktur...",
        "type": "TEXT",
        "reference": [
          {"url": "https://www.alibabacloud.com/help/document_detail/463469.html", "title": "Pengenalan Produk OpenSearch"}
        ]
      }
    ],
    "search_hits": [
      {
        "fields": {"content": "Konten dokumen terkait OpenSearch...", "title": "Pengenalan OpenSearch"},
        "scores": ["0.9778"],
        "type": "DOC"
      }
    ]
  }
}

Respons kesalahan

{
  "request_id": "e579a090bf99dc787d29d878b40c8367",
  "status": "FAIL",
  "errors": [
    {"code": 3005, "message": "topN[51] is not in (0, 50]"}
  ]
}