Instrumentar o uso do Microsoft Web IQ

Este guia explica como implementar a telemetria ao usar Web IQ APIs para registrar em log o uso de conteúdo de grounding.

Overview

As Web IQ APIs podem ser instrumentadas para incluir campos de telemetria em respostas, permitindo que seu aplicativo registre métricas de interação do usuário por meio de solicitações HTTP.

Cenários de telemetria com suporte:

  • Uso de LLM: Registre quais resultados de pesquisa um Modelo de Linguagem de Grande Porte (LLM) referencia ao criar sua resposta.
  • Cliques do usuário final: registrar em log em quais citações um usuário clica depois de ser apresentado a um resumo e citações pelo LLM.

Habilitar instrumentação

Para registrar eventos, a instrumentação deve ser habilitada no perfil de Web IQ APIs. Entre em contato com seu contato da Microsoft para configurar isso.

Resposta

Depois de habilitar a instrumentação, as respostas à API incluirão campos de 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"
}

Descrições de campo

Field Description
instrumentationClickBase URL base para registrar cliques do usuário final. IG (GUID de impressão) e CID (ID do cliente) são pré-preenchidos. ID deve ser acrescentado manualmente com instrumentationSuffix.
instrumentationCitationBase URL base para relatar o uso de LLM. Inclui IG e CID. Type deve ser "Event.ClientInst". DATA é um array JSON de eventos codificado em URL.
instrumentationSuffix Identificador exclusivo por resultado usado para registro em log (por exemplo, DevEx,1000).
clickUrl Se o redirecionamento estiver habilitado, cada resultado incluirá clickUrluma URL de redirecionamento que encaminha o usuário final para a URL de destino original. Com clickUrl, você não precisa registrar eventos de clique manualmente, mas ainda precisa registrar o uso de LLM manualmente.

Note

Quando o redirecionamento estiver habilitado no perfil, instrumentationClickBase não será incluído na resposta.

O exemplo a seguir mostra uma resposta da API Web IQ quando os pings de instrumentação e o redirecionamento de URL estão habilitados.

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

Implementação de Exemplo

Solicitação

Ponto de extremidade:POST https://api.microsoft.ai/v3/search/web

Solicitação de exemplo:

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

Resposta (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"
}

Fluxo de trabalho de telemetria

Etapa 1: Fornecer Citações

Inclua citações na resposta LLM ao usuário.

Etapa 2: Registrar uso de LLM

Crie um array de objetos com estes campos:

Field Value
T subtipo que representa a categoria de informações. Deve ser sempre "CI.Info"
FID ID do recurso. Deve ser sempre "LLM"
Name nome do evento para mais informações sobre a classificação. (por exemplo, "citação")
AppNS Prefixo de instrumentationSuffix (por exemplo, "DevEx")
K Valor do sufixo (por exemplo, "1000")

Conteúdo de exemplo:

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

Codificar URL do array:

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

e envie por meio de:

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

Etapa 3: Registrar cliques do usuário

Quando um usuário clicar em uma citação, envie:

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

  • Última atualização em