Microsoft Web IQ-Nutzung instrumentieren

In diesem Handbuch wird erläutert, wie Telemetrie implementiert wird, wenn Web IQ-APIs zum Protokollieren der Nutzung von Grounding-Inhalten verwendet werden.

Overview

Web IQ-APIs können instrumentiert werden, um Telemetriefelder in Antworten einzuschließen, sodass Ihre Anwendung Benutzerinteraktionsmetriken über HTTP-Anforderungen protokollieren kann.

Unterstützte Telemetrieszenarien:

  • LLM-Verwendung: Protokollieren Sie, welche Suchergebnisse ein Large Language Model (LLM) beim Erstellen seiner Antwort heranzieht.
  • Endbenutzerklicks: Protokollieren, welche Zitate ein Benutzer anklickt, nachdem eine Zusammenfassung und Zitate von der LLM angezeigt wurden.

Instrumentierung aktivieren

Zum Protokollieren von Ereignissen muss die Instrumentierung in Ihrem Web IQ-APIs-Profil aktiviert sein. Wenden Sie sich an Ihren Microsoft Kontakt, um dies zu konfigurieren.

Antwort

Nach dem Aktivieren der Instrumentierung umfassen API-Antworten Telemetriefelder:

{
  "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"
}

Feldbeschreibungen

Feld Description
instrumentationClickBase Basis-URL zum Melden von Endbenutzerklicks. IG (Impression GUID) und CID (Client-ID) werden vorab aufgefüllt. ID muss manuell mit instrumentationSuffix ergänzt werden.
instrumentationCitationBase Basis-URL für die Berichterstellung der LLM-Verwendung. Enthält IG und CID. Type muss den Wert "Event.ClientInst" haben. DATA ist ein URL-codiertes JSON-Array von Ereignissen.
instrumentationSuffix Eindeutiger Bezeichner pro Ergebnis, der für die Protokollierung verwendet wird (z. B. DevEx,1000).
clickUrl Wenn die Umleitung aktiviert ist, enthält jedes Ergebnis clickUrl eine Umleitungs-URL, die den Endbenutzer an die ursprüngliche Ziel-URL weiterleitet. Mit clickUrl müssen Sie keine Klickereignisse manuell protokollieren, aber Sie müssen die LLM-Verwendung trotzdem manuell protokollieren.

Note

Wenn die Umleitung im Profil aktiviert ist, wird instrumentationClickBase nicht in die Antwort einbezogen.

Das folgende Beispiel zeigt eine Web IQ-API-Antwort, wenn sowohl Instrumentierungs-Pings als auch URL-Umleitung aktiviert sind.

{
  "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"
}

Beispielimplementierung

Anfrage

Endpunkt:POST https://api.microsoft.ai/v3/search/web

Beispielanforderung:

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"
  }'

Antwort (vereinfacht)

{
  "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"
}

Telemetrieworkflow

Schritt 1: Bereitstellen von Quellenangaben

Fügen Sie Quellenangaben in die LLM-Antwort auf den Benutzer ein.

Schritt 2: LLM-Verwendung protokollieren

Erstellen Sie ein Array von Objekten mit den folgenden Feldern:

Feld Wert
T Untertyp, der die Kategorie der Informationen darstellt. Es sollte immer "CI.Info" sein
FID Feature-ID. Es sollte immer "LLM" sein
Name Ereignisname für weitere Informationen zur Klassifizierung. (z. B. "Zitat")
AppNS Präfix von instrumentationSuffix (z. B. "DevEx")
K Suffixwert (z. B. "1000")

Beispiel-Payload:

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

URL-kodieren Sie das Array:

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

und senden Sie über:

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

Schritt 3: Benutzerklicks protokollieren

Wenn ein Benutzer auf eine Quellenangabe klickt, senden Sie Folgendes:

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

  • Zuletzt aktualisiert um