Instrumentar a utilização do Microsoft Web IQ

Este guia explica como implementar telemetria ao utilizar APIs Web IQ para registar o uso de conteúdos de grounding.

Overview

As APIs Web IQ podem ser instrumentadas para incluir campos de telemetria nas respostas, permitindo que a sua aplicação registe métricas de interação do utilizador através de pedidos HTTP.

Cenários de telemetria suportados:

  • Utilização do LLM: Registar quais resultados de pesquisa um Grande Modelo de Linguagem (LLM) refere ao criar a sua resposta.
  • Cliques do utilizador final: Regista em quais citações um utilizador clica depois de lhe serem apresentados um resumo e citações pelo LLM.

Ativar instrumentação

Para registar eventos, a instrumentação deve estar ativada no seu perfil do Web IQ APIs. Contacte o seu contacto da Microsoft para configurar isto.

Resposta

Após ativar a instrumentação, as respostas da 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 dos campos

Field Description
instrumentationClickBase URL de base para comunicar cliques do utilizador final. IG (GUID de Impressão) e CID (ID do Cliente) estão pré-preenchidos. ID deve ser acrescentado manualmente com instrumentationSuffix.
instrumentationCitationBase URL base para reportar o uso de LLMs. Inclui IG e CID. Type deve ser "Event.ClientInst". DATA é um array JSON codificado em URL de eventos.
instrumentationSuffix Identificador único por resultado usado para registo (por exemplo, DevEx,1000).
clickUrl Se o redirecionamento estiver ativado, cada resultado inclui clickUrl, um URL de redirecionamento que encaminha o utilizador final para o URL de destino original. Com clickUrl, NÃO precisas de registar manualmente os eventos de clique, mas ainda assim precisas de registar o uso do LLM manualmente.

Note

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

O exemplo seguinte mostra uma resposta da API Web IQ quando tanto os pings de instrumentação como a redireção de URL estão ativados.

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

Exemplo de implementação

Request

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

Pedido 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

Passo 1: Fornecer Citações

Inclua citações na resposta do LLM ao utilizador.

Passo 2: Registar a utilização de LLM

Construa um array de objetos com estes campos:

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

Exemplo de carga útil:

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

Codifique o array em URL:

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

e enviar via:

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

Passo 3: Registar os Cliques do Utilizador

Quando um utilizador clica numa citação, envie:

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

  • Última atualização a