Monitoruj użycie Microsoft Web IQ

W tym przewodniku wyjaśniono, jak zaimplementować dane telemetryczne podczas korzystania z interfejsów API Web IQ w celu rejestrowania użycia treści ugruntowującej.

Overview

Interfejsy API Web IQ APIs można instrumentować w celu uwzględnienia pól telemetrii w odpowiedziach, dzięki czemu aplikacja może rejestrować metryki interakcji użytkowników za pośrednictwem żądań HTTP.

Obsługiwane scenariusze telemetrii:

  • Użycie modelu LLM: Rejestruj, do których wyników wyszukiwania odwołuje się model dużego języka (LLM) podczas tworzenia odpowiedzi.
  • Kliknięcia użytkownika końcowego: Rejestruj, które cytaty użytkownik klika po przedstawieniu przez LLM podsumowania i cytatów.

Włączanie telemetrii

Aby rejestrować zdarzenia, instrumentacja musi być włączona w profilu interfejsów API Web IQ. Skontaktuj się ze swoją osobą kontaktową w firmie Microsoft, aby to skonfigurować.

Odpowiedź

Po włączeniu instrumentacji odpowiedzi interfejsu API będą zawierać pola telemetrii:

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

Opisy pól

Pole Description
instrumentationClickBase Podstawowy adres URL do raportowania kliknięć użytkowników końcowych. IG (Impression GUID) i CID (Identyfikator klienta) są wstępnie wypełniane. ID należy ręcznie uzupełnić o instrumentationSuffix.
instrumentationCitationBase Podstawowy adres URL do raportowania użycia LLM. Zawiera IG i CID. Type musi mieć wartość "Event.ClientInst". DATA to tablica zdarzeń JSON zakodowana metodą URL encoding.
instrumentationSuffix Unikatowy identyfikator dla każdego wyniku używany do rejestrowania (np. DevEx,1000).
clickUrl Jeśli przekierowanie jest włączone, każdy wynik zawiera clickUrladres URL przekierowania, który przekazuje użytkownika końcowego do oryginalnego docelowego adresu URL. Dzięki clickUrl nie trzeba ręcznie rejestrować zdarzeń kliknięć, ale nadal musisz ręcznie rejestrować użycie usługi LLM.

Note

Po włączeniu przekierowania w profilu instrumentationClickBase nie będzie uwzględniane w odpowiedzi.

W poniższym przykładzie pokazano odpowiedź Web IQ API po włączeniu zarówno pingów instrumentacji, jak i przekierowania adresu 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"
}

Przykładowa implementacja

Żądanie

Punkt końcowy:POST https://api.microsoft.ai/v3/search/web

Przykładowe żądanie:

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

Odpowiedź (uproszczona)

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

Przepływ telemetrii

Krok 1: Podaj cytaty

Dołącz cytowania w odpowiedzi LLM dla użytkownika.

Krok 2: Rejestrowanie użycia LLM

Utwórz tablicę obiektów przy użyciu następujących pól:

Pole Value
T podtyp reprezentujący kategorię informacji. Zawsze powinno to być "CI.Info"
FID identyfikator funkcji. Zawsze powinno to być "LLM"
Name nazwa zdarzenia w celu uzyskania dalszych informacji na potrzeby klasyfikacji. (np. "cytat")
AppNS Prefiks instrumentationSuffix (np. "DevEx")
K Wartość sufiksu (np. "1000")

Przykładowy ładunek:

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

Zakoduj tablicę w adresie URL:

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

i wyślij za pośrednictwem:

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

Krok 3. Rejestrowanie kliknięć użytkownika

Gdy użytkownik kliknie cytat, wyślij:

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

  • Ostatnia aktualizacja o