Strumentare l'utilizzo di Microsoft Web IQ

Questa guida illustra come implementare i dati di telemetria quando si usano le API Web IQ per registrare l'utilizzo dei contenuti di grounding.

Overview

Le API IQ Web possono essere instrumentate per includere i campi di telemetria nelle risposte, consentendo all'applicazione di registrare le metriche di interazione dell'utente tramite richieste HTTP.

Scenari di telemetria supportati:

  • Utilizzo dell'LLM: registra quali risultati di ricerca un modello di linguaggio di grandi dimensioni (LLM) utilizza come riferimento durante la creazione della risposta.
  • Clic dell'utente: registrare le citazioni su cui un utente fa clic dopo aver visualizzato un riepilogo e citazioni dall'LLM.

Abilitare la telemetria

Per registrare gli eventi, la strumentazione software deve essere abilitata nel profilo Web IQ APIs. Per configurare questa operazione, contattare il contatto Microsoft.

Risposta

Dopo aver abilitato la strumentazione, le risposte api includeranno i campi di telemetria:

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

Descrizioni dei campi

Field Description
instrumentationClickBase URL di base per la segnalazione dei clic dell'utente finale. IG (GUID impression) e CID (ID client) sono prepopolati. ID deve essere integrato con instrumentationSuffix manualmente.
instrumentationCitationBase URL di base per la segnalazione dell'utilizzo LLM. Include IG e CID. Il parametro Type deve essere impostato su "Event.ClientInst". DATA è un array JSON con codifica URL di eventi.
instrumentationSuffix Identificatore univoco per risultato usato per la registrazione (ad esempio, DevEx,1000).
clickUrl Se il reindirizzamento è abilitato, ogni risultato include clickUrl, un URL di reindirizzamento che inoltra l'utente finale all'URL di destinazione originale. Con clickUrlnon è necessario registrare manualmente gli eventi click, ma è comunque necessario registrare manualmente l'utilizzo LLM.

Note

Quando il reindirizzamento è abilitato nel profilo, instrumentationClickBase non verrà incluso nella risposta.

L'esempio seguente mostra una risposta API Web IQ quando sono abilitati sia i ping di strumentazione sia il reindirizzamento URL.

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

Implementazione di esempio

Richiesta

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

Richiesta di esempio:

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

Risposta (semplificata)

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

Workflow di telemetria

Passaggio 1: Fornire citazioni

Includi citazioni nella risposta LLM all'utente.

Passaggio 2: Registrare l'utilizzo LLM

Creare un array di oggetti con questi campi:

Field Value
T sottotipo che rappresenta la categoria di informazioni. Deve essere sempre "CI.Info"
FID ID della funzionalità. Deve essere sempre "LLM"
Name nome dell'evento per ulteriori informazioni sulla classificazione. (ad esempio, "citazione")
AppNS Prefisso di instrumentationSuffix (ad esempio, "DevEx")
K Valore suffisso (ad esempio, "1000")

Esempio di payload:

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

Codificare l'URL dell'array:

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

e inviare tramite:

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

Passaggio 3: Registra i clic degli utenti

Quando un utente fa clic su una citazione, inviare:

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

  • Ultimo aggiornamento: