Microsoft Web IQ kullanımını izleyin

Bu kılavuzda, grounding içeriği kullanımını günlüğe kaydetmek için Web IQ API'lerini kullanırken telemetrinin nasıl uygulanacağı açıklanmaktadır.

Overview

Web IQ API'leri, yanıtlara telemetri alanlarını dahil edecek şekilde yapılandırılabilir ve uygulamanızın HTTP istekleri aracılığıyla kullanıcı etkileşimi ölçümlerini günlüğe kaydetmesini sağlar.

Desteklenen telemetri senaryoları:

  • LLM kullanımı: Bir Büyük Dil Modelinin (LLM) yanıtını oluştururken başvurduğu arama sonuçlarını günlüğe kaydedin.
  • Son kullanıcı tıklamaları: LLM tarafından özetleme ve alıntılar sunulduktan sonra kullanıcının tıkladığı alıntıları günlüğe kaydetme.

Enstrümantasyonu Etkinleştirme

Olayları günlüğe kaydetmek için enstrümantasyonun Web IQ API'leri profilinizde etkinleştirilmesi gerekir. Bunu yapılandırmak için Microsoft irtibat kişinize başvurun.

Response

İzlemeyi etkinleştirdikten sonra API yanıtları telemetri alanlarını içerir:

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

Alan Açıklamaları

Field Description
instrumentationClickBase Son kullanıcı tıklamalarını raporlamaya yönelik temel URL. IG (Gösterim GUID'si) ve CID (İstemci Kimliği) önceden doldurulur. ID, instrumentationSuffix ile manuel olarak eklenmelidir.
instrumentationCitationBase LLM kullanımını raporlamaya yönelik temel URL. IG ve CID içerir. Type olmalıdır "Event.ClientInst". DATA, olayların URL ile kodlanmış bir JSON dizisidir.
instrumentationSuffix Günlük kaydı için kullanılan sonuç başına benzersiz tanımlayıcı (örn. DevEx,1000).
clickUrl Yeniden yönlendirme etkinleştirilirse her sonuç, clickUrl, son kullanıcıyı özgün hedef URL'ye ileden bir yeniden yönlendirme URL'si içerir. clickUrl ile tıklama olaylarını el ile günlüğe kaydetmeniz gerekmez, ancak yine de LLM kullanımını el ile günlüğe kaydetmeniz gerekir.

Note

Profilde yeniden yönlendirme etkinleştirildiğinde yanıta instrumentationClickBase dahil edilmeyecektir.

Aşağıdaki örnekte, izleme ping'leri ve URL yeniden yönlendirme etkinleştirildiğinde bir Web IQ API yanıtı gösterilmektedir.

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

Örnek Uygulama

İstek

Bitiş noktası:POST https://api.microsoft.ai/v3/search/web

Örnek İstek:

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

Yanıt (Basitleştirilmiş)

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

Telemetri İş Akışı

1. Adım: Alıntılar Sağlayın

LLM yanıtına kullanıcıya yönelik atıflar ekleyin.

2. Adım: LLM Kullanımını Günlüğe Kaydetme

Şu alanlarla bir nesne dizisi oluşturun:

Field Value
T bilgi kategorisini temsil eden alt tür. Her zaman "CI.Info" olmalıdır
FID özellik kimliği. Her zaman "LLM" olmalıdır
Name sınıflandırma için daha fazla bilgi amacıyla etkinlik adı. (örn. "alıntı")
AppNS ön eki instrumentationSuffix (örn. "DevEx")
K sonek değeri (örn. "1000")

Örnek yük:

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

Diziyi URL kodlamasıyla kodlayın:

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

ve şu yolla gönderin:

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

3. Adım: Kullanıcı Tıklamalarını Günlüğe Kaydet

Kullanıcı alıntıya tıkladığında şunları gönderin:

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

  • Son güncelleştirme: