Instrumentar el uso de Microsoft Web IQ

En esta guía se explica cómo implementar la telemetría al usar las API de Web IQ para registrar el uso del contenido de grounding.

Overview

Las API de Web IQ se pueden instrumentar para incluir campos de telemetría en respuestas, lo que permite que la aplicación registre las métricas de interacción del usuario a través de solicitudes HTTP.

Escenarios de telemetría admitidos:

• Uso de LLM: Registrar qué resultados de búsqueda referencia un modelo de lenguaje grande (LLM) al crear su respuesta.
• Clics del usuario final: registre las citas en las que un usuario hace clic después de que se le presenten un resumen y las citas proporcionadas por el LLM.

Habilitación de la instrumentación

Para registrar eventos, la instrumentación debe estar habilitada en el perfil de APIs de Web IQ. Póngase en contacto con su contacto de Microsoft para configurarlo.

Respuesta

Después de habilitar la instrumentación, las respuestas de API incluirán campos de telemetría:

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

Descripciones de campo

Field	Description
instrumentationClickBase	Dirección URL base para registrar clics de usuario final. IG (GUID de impresión) y CID (id. de cliente) se rellenan previamente. instrumentationSuffix debe anexarse manualmente a ID.
instrumentationCitationBase	Dirección URL base para notificar el uso de LLM. Incluye IG y CID. Type debe ser "Event.ClientInst". DATA es un array JSON de eventos codificado en URL.
instrumentationSuffix	Identificador único por resultado usado para el registro (por ejemplo, DevEx,1000).
clickUrl	Si el redireccionamiento está habilitado, cada resultado incluye clickUrl, una dirección URL de redireccionamiento que reenvía al usuario final a la dirección URL de destino original. Con clickUrl, no es necesario registrar manualmente los eventos de clic, pero todavía necesita registrar el uso de LLM manualmente.

Note

Cuando el redireccionamiento está habilitado en el perfil, instrumentationClickBase no se incluirá en la respuesta.

En el ejemplo siguiente se muestra una respuesta de API de Web IQ cuando se habilitan los pings de instrumentación y la redirección de direcciones 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"
}

Implementación de ejemplo

Solicitud

Punto final:POST https://api.microsoft.ai/v3/search/web

Solicitud de ejemplo:

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

Respuesta (Simplificada)

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

Flujo de trabajo de telemetría

Paso 1: Proporcionar referencias

Incluya citas en la respuesta llm al usuario.

Paso 2: Registro del uso de LLM

Cree una matriz de objetos con estos campos:

Field	Value
T	subtipo que representa la categoría de información. Siempre debe ser "CI.Info"
FID	ID de la característica. Siempre debe ser "LLM"
Name	nombre del evento para obtener más información para la clasificación. (por ejemplo, "cita")
AppNS	Prefijo de instrumentationSuffix (por ejemplo, "DevEx")
K	Valor de sufijo (por ejemplo, "1000")

Carga de ejemplo:

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

Codifique en URL el array:

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

y envíe mediante:

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

Paso 3: Registrar clics de usuario

Cuando un usuario hace clic en una cita bibliográfica, envíe:

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