Instrumentasikan penggunaan Microsoft Web IQ

Panduan ini menjelaskan cara menerapkan telemetri saat menggunakan API Web IQ untuk mencatat penggunaan konten grounding.

Overview

API IQ Web dapat diinstrumentasikan untuk menyertakan bidang telemetri dalam respons, memungkinkan aplikasi Anda mencatat metrik interaksi pengguna melalui permintaan HTTP.

Skenario telemetri yang didukung:

  • Penggunaan LLM: Mencatat hasil penelusuran mana yang dirujuk Model Bahasa Besar (LLM) saat membuat responsnya.
  • Klik pengguna akhir: Mencatat kutipan mana yang diklik pengguna setelah disajikan dengan ringkasan dan kutipan oleh LLM.

Mengaktifkan Instrumentation

Untuk mencatat peristiwa, instrumentasi harus diaktifkan di profil Web IQ APIs Anda. Hubungi kontak Microsoft Anda untuk mengonfigurasi ini.

Jawaban

Setelah mengaktifkan instrumentasi, respons API akan mencakup bidang telemetri:

{
  "webResults": [
    {
      "...": "...",
      "instrumentationSuffix": "DevEx,1000"
    }
  ],
  "instrumentationClickBase": "https://api.microsoft.ai/api/ping?IG=some-impression-id&CID=some-client-id&ID=",
  "instrumentationCitationBase": "https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=",
  "traceId": "some-trace-id"
}

Deskripsi Bidang

Field Description
instrumentationClickBase URL dasar untuk melaporkan klik pengguna akhir. IG (GUID Tayangan) dan CID (ID Klien) telah diisi sebelumnya. ID harus diikuti dengan instrumentationSuffix secara manual.
instrumentationCitationBase URL Dasar untuk melaporkan penggunaan LLM. Termasuk IG dan CID. Type harus merupakan "Event.ClientInst". DATA adalah array peristiwa JSON yang dikodekan URL.
instrumentationSuffix Pengidentifikasi unik per hasil yang digunakan untuk pengelogan (misalnya, DevEx,1000).
clickUrl Jika pengalihan diaktifkan, setiap hasil menyertakan clickUrl, URL pengalihan yang meneruskan pengguna akhir ke URL tujuan asli. Dengan clickUrl, Anda TIDAK perlu mencatat peristiwa klik secara manual, tetapi Anda masih perlu mencatat penggunaan LLM secara manual.

Note

Ketika pengalihan diaktifkan di profil, instrumentationClickBase tidak akan disertakan dalam respons.

Contoh berikut menunjukkan respons API IQ Web saat ping instrumentasi dan pengalihan URL diaktifkan.

{
  "webResults": [
    {
      "url": "original-destination-link",
      "clickUrl": "encoded-redirection-link",
      "instrumentationSuffix": "DevEx,1000"
    }
  ],
  "instrumentationCitationBase": "https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=",
  "traceId": "some-trace-id"
}

Contoh Implementasi

Request

Titik Akhir:POST https://api.microsoft.ai/v3/search/web

Permintaan Sampel:

curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "webiq",
    "maxResults": 10,
    "language": "en",
    "region": "US",
    "maxLength": 3000,
    "contentFormat": "passage"
  }'

Respons (Sederhana)

{
  "webResults": [
    {
      "title": "Microsoft Web IQ",
      "url": "https://www.microsoft.com/en-us/webiq",
      "content": "...",
      "crawledAt": "2026-06-17T22:29:00.0000000Z",
      "language": "en",
      "isAdult": false,
      "instrumentationSuffix": "DevEx,1000"
    },
    {
      "title": "WebIQ - The Web HMI System for Professional HMIs",
      "url": "https://www.smart-hmi.com/",
      "content": "...",
      "crawledAt": "2026-06-16T01:17:00.0000000Z",
      "language": "en",
      "isAdult": false,
      "instrumentationSuffix": "DevEx,1001"
    }
  ],
  "instrumentationClickBase": "https://api.microsoft.ai/api/ping?IG=some-impression-id&CID=some-client-id&ID=",
  "instrumentationCitationBase": "https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=",
  "traceId": "some-trace-id"
}

Alur Kerja Telemetri

Langkah 1: Berikan Referensi

Sertakan kutipan dalam respons LLM kepada pengguna.

Langkah 2: Mencatat Penggunaan LLM

Buat array objek dengan bidang ini:

Field Value
T subjenis yang mewakili kategori informasi. Harus selalu "CI.Info"
FID ID fitur. Ini harus selalu "LLM"
Name nama acara untuk informasi klasifikasi lebih lanjut. (misalnya, "kutipan")
AppNS Awalan instrumentationSuffix (misalnya, "DevEx")
K Nilai akhiran (misalnya, "1000")

Contoh payload:

[
  {
    "T": "CI.Info",
    "FID": "LLM",
    "Name": "citation",
    "AppNS": "DevEx",
    "K": "1000"
  },
  {
    "T": "CI.Info",
    "FID": "LLM",
    "Name": "citation",
    "AppNS": "DevEx",
    "K": "1001"
  }
]

URL-encode array tersebut:

var encoded_array = encodeURIComponent(JSON.stringify(data_array));

dan kirim melalui:

Titik Akhir:GET https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=<encoded_array>

Langkah 3: Catat klik pengguna

Saat pengguna mengklik kutipan, kirim:

Titik Akhir:GET https://api.microsoft.ai/api/ping?IG=some-impression-id&CID=some-client-id&ID=DevEx,1001

  • Terakhir diperbarui pada