이 가이드에서는 Web IQ API를 사용하여 그라운딩 콘텐츠 사용을 기록할 때 원격 분석을 구현하는 방법을 설명합니다.
Overview
웹 IQ API를 계측하여 응답에 원격 분석 필드를 포함할 수 있으므로 애플리케이션이 HTTP 요청을 통해 사용자 상호 작용 메트릭을 기록할 수 있습니다.
지원되는 원격 분석 시나리오:
- LLM 사용: LLM(큰 언어 모델)이 응답을 생성할 때 참조한 검색 결과를 기록합니다.
- 최종 사용자 클릭: LLM에서 요약 및 출처를 표시한 후 사용자가 클릭하는 출처를 기록합니다.
계측 활성화
이벤트를 기록하려면 Web IQ API 프로필에서 계측을 사용하도록 설정해야 합니다. 이를 구성하려면 Microsoft 담당자에게 문의하세요.
응답
계측을 사용하도록 설정한 후 API 응답에는 원격 분석 필드가 포함됩니다.
{
"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"
}
필드 설명
| Field | Description |
|---|---|
instrumentationClickBase |
최종 사용자 클릭을 보고하기 위한 기본 URL입니다.
IG (노출 GUID) 및 CID (클라이언트 ID)는 미리 채워집니다.
ID에 instrumentationSuffix를 수동으로 추가해야 합니다. |
instrumentationCitationBase |
LLM 사용량을 보고하기 위한 기본 URL입니다.
IG 및 CID을 포함합니다.
Type는 "Event.ClientInst"이어야 합니다.
DATA 는 URL로 인코딩된 JSON 이벤트 배열입니다. |
instrumentationSuffix |
로깅에 사용되는 결과당 고유 식별자(예: DevEx,1000)입니다. |
clickUrl |
리디렉션을 사용하는 경우 각 결과에는 clickUrl 최종 사용자를 원래 대상 URL로 전달하는 리디렉션 URL이 포함됩니다.
clickUrl를 사용하면 클릭 이벤트를 수동으로 기록할 필요는 없지만 LLM 사용량은 여전히 수동으로 기록해야 합니다. |
Note
프로필에서 리디렉션을 사용하도록 설정하면 instrumentationClickBase는 응답에 포함되지 않습니다.
다음 예제에서는 계측 ping과 URL 리디렉션을 모두 사용할 때 웹 IQ API 응답을 보여 줍니다.
{
"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"
}
구현 예제
요청
끝점:POST https://api.microsoft.ai/v3/search/web
샘플 요청:
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"
}'
응답 (간소화됨)
{
"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"
}
텔레메트리 워크플로
1단계: 인용 제공
사용자에게 제공하는 LLM 응답에 인용을 포함합니다.
2단계: LLM 사용 현황 기록
다음 필드를 사용하여 개체 배열을 빌드합니다.
| Field | Value |
|---|---|
T |
정보의 범주를 나타내는 하위 형식입니다. 항상 "CI.Info"이어야 합니다. |
FID |
기능 ID. 항상 "LLM"이어야 합니다. |
Name |
분류를 위한 추가 정보용 이벤트 이름입니다. (예: "인용") |
AppNS |
접두사 instrumentationSuffix (예: "DevEx") |
K |
접미사 값(예: "1000") |
페이로드 예제:
[
{
"T": "CI.Info",
"FID": "LLM",
"Name": "citation",
"AppNS": "DevEx",
"K": "1000"
},
{
"T": "CI.Info",
"FID": "LLM",
"Name": "citation",
"AppNS": "DevEx",
"K": "1001"
}
]
배열을 URL 인코딩:
var encoded_array = encodeURIComponent(JSON.stringify(data_array));
그리고 다음을 통해 전송:
끝점:GET https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=<encoded_array>
3단계: 사용자 클릭 기록
사용자가 인용을 클릭하면 다음을 보냅니다.
끝점:GET https://api.microsoft.ai/api/ping?IG=some-impression-id&CID=some-client-id&ID=DevEx,1001