API Analisis Query - OpenSearch

Topik ini menjelaskan detail API untuk layanan analisis query.

Nama Layanan

ID Layanan

Deskripsi Layanan

Batas QPS untuk panggilan API (Akun Alibaba Cloud dan Pengguna RAM)

Layanan analisis query

ops-query-analyze-001

Menyediakan layanan analisis konten query yang didukung oleh model bahasa besar dan kemampuan NLP. Layanan ini mencakup deteksi niat, ekspansi pertanyaan serupa, dan pemrosesan NL2SQL untuk query input pengguna, secara efektif meningkatkan kinerja pengambilan dan pembuatan jawaban dalam skenario RAG.

Untuk menggunakan layanan NL2SQL, Anda harus terlebih dahulu mengonfigurasi informasi seperti skema tabel dan contoh query di Konsol. Untuk informasi lebih lanjut, lihat Konfigurasikan fitur NL2SQL. Setelah konfigurasi, Anda dapat memanggil Layanan Analisis Query - NL2SQL melalui API dengan mengikuti petunjuk dalam dokumen ini.

Catatan

Untuk mengajukan QPS yang lebih tinggi, ajukan tiket.

Informasi otentikasi harus diperoleh.
Saat memanggil layanan Platform Terbuka AI Search menggunakan API, Anda perlu mengotentikasi identitas pemanggil.
Alamat akses layanan harus diperoleh.
Anda dapat memanggil layanan melalui Internet atau virtual private cloud (VPC). Untuk informasi lebih lanjut, lihat Dapatkan alamat pendaftaran layanan.

Deskripsi Umum

Badan permintaan tidak boleh melebihi 8MB.

Metode Permintaan

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/query-analyze/{service_id}

host: Alamat untuk memanggil layanan, mendukung pemanggilan API melalui jaringan publik dan VPC. Untuk informasi lebih lanjut, lihat Titik akhir layanan query.
service_id: ID layanan bawaan sistem, seperti ops-query-analyze-001.

Parameter Permintaan

Parameter Header

Otentikasi API-KEY

Parameter	Tipe	Diperlukan	Deskripsi	Nilai contoh
Content-Type	String	Ya	Tipe permintaan: application/json	application/json
Authorization	String	Ya	API-Key	Bearer OS-d1**2a

Parameter Body

Parameter	Tipe	Diperlukan	Deskripsi	Nilai contoh
query	String	Ya	Konten permintaan ini.	Berapa banyak orang?
history	List<Message>	Tidak	Pesan sejarah.	[{ "content": "Di mana ibu kota Tiongkok", "role": "user" }, { "content": "Beijing", "role": "assistant" }]
history.content	String	Tidak	Konten pesan.	Di mana ibu kota Tiongkok
history.role	String	Tidak	Pengirim pesan, nilai opsi saat ini untuk peran: system, user, assistant.	user
functions	List<Function>	Tidak	Fungsi yang diaktifkan dan parameter yang sesuai. Nilai valid: pre:Pra-pemrosesan. intent:Deteksi niat. similar_query:Ekspansi query serupa nl2sql:Bahasa alami ke SQL Catatan: Secara default, pre, intent, dan similar_query diaktifkan. Saat nl2sql diaktifkan, intent dan similar_query dinonaktifkan secara default.
functions[].name	String	Tidak	Jika Anda menentukan fungsi, Anda harus menentukan nama.
functions[].parameters	Map	Tidak	Parameter fungsi.
functions[].parameters.enable	boolean	Tidak	Menentukan apakah akan mengaktifkan fungsi.	true

Parameter Tanggapan

Parameter	Tipe	Deskripsi	Nilai contoh
request_id	String	Pengenal unik yang ditetapkan oleh sistem untuk panggilan API.	A5B25952-4406-45BF-99EC-E8020246****
latency	Float/Int	Durasi permintaan, dalam ms.	10
result.query	String	Permintaan yang diproses.	Berapa banyak orang
result.queries	List<String>	Query alternatif yang dihasilkan.	[ "Berapa banyak orang di Beijing" ]
result.intent	String	Hasil deteksi niat.	Q&A pair
result.sql	Map	Hasil nl2sql.

Contoh Permintaan Curl

curl -XPOST -H"Content-Type: application/json" 
\http://****.opensearch.aliyuncs.com/v3/openapi/workspaces/default/query-analyze/ops-query-analyze-001\
    -H "Authorization: Bearer Your API-Key" \
    -d'{
      "query":"Kelas apa Jack berada",
      "history":[
          {
            "role":"user",
            "content":"Di mana ibu kota Tiongkok"
          },
          {
            "role":"assistant",
            "content":"Beijing"
          }
        ],
        "functions":[
          {
            "name":"pre",
            "parameters":
              {
                "enable":true
              }
          },
          {
            "name":"intent",
            "parameters":
              {
                "enable":true
              }
            },
            {
              "name":"similar_query",
              "parameters":
                {
                  "enable":true
                }
              },
              {
                "name":"nl2sql",
                "parameters":
                  {
                    "enable":true,
                    "config_name":"n_1726047726"
                  }
                }
              ]
            }'

Contoh Tanggapan

Contoh tanggapan normal

{
  "request_id":"023FC760-E273-4163-B2DA-5CF28E2A****",
  "latency":6383,
  "usage":{
      "total_tokens":1082,
      "output_tokens":41,
      "input_tokens":1041
    },
    "result":{
      "query":"Kelas apa Jack berasal",
      "queries":[
          "Kelas Jack berasal"
      ],
      "intent":"Q&A",
      "sql":{
          "text":"SELECT students.class FROM students WHERE students.name = 10002;"
      }
    }
}

Contoh tanggapan abnormal

Jika terjadi kesalahan dalam permintaan akses, hasil keluaran akan menunjukkan alasan kesalahan melalui kode dan pesan.

{
  "request_id":"19C54DAA-AD50-4B37-A48C-912A8F82****",
  "latency":0,
  "code":"InvalidParameter",
  "message":"Parameter wajib: query hilang atau tidak valid, harap periksa parameter permintaan."
}

Deskripsi Kode Status

Kode status HTTP	Kode kesalahan	Deskripsi
200	-	Permintaan berhasil, termasuk skenario kegagalan tugas. Status tugas aktual perlu ditentukan dari result.status.
404	BadRequest.TaskNotExist	Tugas tidak ada.
400	InvalidParameter	Permintaan tidak valid.
500	InternalServerError	Kesalahan internal.