사용자 피드백으로 추적에 주석 달기(미리 보기)

Important

이 문서에서 미리 보기로 표시된 항목은 현재 미리 보기로 제공됩니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며 Microsoft 프로덕션 워크로드에 권장하지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.

개별 에이전트 상호작용에 대해 사람이 평가한 품질 신호를 수집하려면 Microsoft Foundry의 추적에 좋아요 또는 싫어요 주석을 추가하세요. 추적 주석을 사용하면 에이전트 응답이 도움이 되었는지 또는 도움이 되지 않는지 여부를 표시할 수 있으며 추적 세부 정보 페이지에 인라인으로 표시되므로 에이전트 동작의 패턴을 빠르게 식별할 수 있습니다.

추적 주석은 다음 두 가지 워크플로를 지원합니다.

  • 작성기 주석: 작성기 및 도메인 전문가는 에이전트 상호 작용을 검토하는 동안 Foundry 포털의 추적에 주석을 추가합니다. 이러한 주석은 builder를 소스로 하여 자동으로 태그 지정됩니다.
  • 최종 사용자 피드백: 최종 사용자가 좋아요 또는 싫어요 피드백을 제공할 때 애플리케이션에서 프로그래밍 방식으로 어노테이션을 로깅할 수 있습니다. 이러한 주석은 end_user를 소스로 가지며, 빌더 주석과 함께 트레이스 페이지에 표시됩니다. 최종 사용자 피드백 로깅에 대한 자세한 내용은 로그 최종 사용자 피드백을 참조하세요.

모든 주석이 추적에 추가 됩니다. 작성기 주석을 추가하면 기존 최종 사용자 피드백을 덮어쓰거나 대체하지 않으며 그 반대의 경우도 마찬가지입니다. 각 주석은 원본 특성을 전달하므로 신호는 독립적으로 쿼리 가능하고 필터링 가능한 상태로 유지됩니다.

Prerequisites

기본 점수 매기기 템플릿

모든 Foundry 프로젝트는 추가 설정 없이 즉시 사용할 수 있는 기본 엄지 손가락 위쪽/아래쪽 채점 템플릿으로 미리 설정됩니다. 첫날에 추적에 주석을 추가할 수 있습니다. 기본 템플릿은 이진 패스/실패 채점을 사용합니다.

  • 좋아요 = 점수 1.0, 레이블 pass
  • 싫어요 = 점수 0.0, 레이블 fail

각 점수 매기기 템플릿에서는 모든 주석이 특정 평가 차원에 귀속되도록 gen_ai.evaluation.name 특성은 값 task_completion을 가져야 합니다. task_completion 는 엄지 손가락을 위아래로 지원합니다.

Foundry 포털에서 추적에 주석 달기

추적 세부 정보 페이지에서 직접 주석을 추가하여 에이전트 응답 평가를 기록합니다.

  1. Foundry 프로젝트를 열고 왼쪽 탐색 영역에서 추적 으로 이동합니다.
  2. 추적을 선택하여 추적 세부 정보 보기를 엽니다.
  3. 추적 세부 정보 페이지에서 오른쪽 위 모서리에 있는 주석 달기 단추를 선택합니다.
  4. 점수를 제출하려면 좋아요 또는 싫어요를 선택하세요. 필요에 따라 자유 텍스트 설명을 추가합니다.
  5. 주석은 즉시 저장되고 추적에 표시됩니다.

Foundry 포털의 추적 세부 정보 페이지에 있는 주석 탭의 스크린샷.

Note

추적 보기 및 주석 저장은 별도의 권한 부여 작업입니다. 추적이 표시되지만 주석을 저장할 수 없는 경우 주석 대상, 실제 쓰기 ID 및 인증 경로를 확인합니다. 다른 추적 읽기 권한 역할을 부여해도 원격 분석 데이터 쓰기 권한은 부여되지 않습니다.

포털에서 추가한 주석에는 자동으로 다음 태그가 지정됩니다:

  • microsoft.gen_ai.human_evaluation.source = "builder"
  • microsoft.gen_ai.evaluation.actor.type = "human"

점수 편집

각 사용자는 여러 번 주석을 달 수 있습니다.

  • 여러 사용자가 각각 동일한 추적에 동일한 형식의 고유한 주석을 가질 수 있습니다.
  • 이전 주석은 Application Insights에서 삭제되지 않습니다. 새 주석이 추가되고 포털에 주석 패널의 주석 기록 섹션에 모든 주석이 표시됩니다.

추적 주석으로 최종 사용자 피드백 기록

최종 사용자가 애플리케이션에서 좋아요 또는 싫어요 피드백을 제공하면, 해당 피드백이 해당 트레이스에 주석으로 표시되도록 기록할 수 있습니다. 이 접근 방식은 gen_ai.evaluation.result OpenTelemetry 이벤트를 사용하며, 피드백은 원래 트레이스에 자동으로 연결됩니다.

주석 특성 스키마

좋아요 또는 싫어요 주석을 생성할 때는 다음 속성을 사용하세요:

Attribute Value Description
gen_ai.evaluation.name task_completion 평가 지표 이름
gen_ai.evaluation.score.value 1.0 (엄지 손가락 위로) 또는 0.0 (엄지 손가락 아래로) 숫자 점수
gen_ai.evaluation.score.label "pass" 또는 "fail" 범주형 레이블
gen_ai.evaluation.explanation 선택적 자유 텍스트 주석 검토자 설명
gen_ai.response.id 예를 들어 "chatcmpl-123" 주석을 추적된 응답과 상호 연결하는 데 사용되는 AI 응답 ID
microsoft.gen_ai.human_evaluation.source "end_user" 또는 "builder" 피드백 공급자 유형
microsoft.gen_ai.evaluation.actor.type "human" 사용자 검토자가 주석을 제출하여 자동화된 평가와 구분했음을 나타냅니다.
operation_Id trace_Id Application Insights의 원래 추적 요청에 주석 연결
operation_ParentId span_Id 주석이 추가되는 추적 내의 특정 범위의 범위 ID를 포함합니다
gen_ai.agent.id 에이전트 리소스 식별자 문자열 주석이 추가되는 응답을 생성한 에이전트의 고유 식별자
gen_ai.agent.name 에이전트 표시 이름 문자열 주석이 추가되는 응답을 생성한 에이전트의 표시 이름
gen_ai.agent.version 버전 문자열 1, 2또는 3 internal_properties 내부에 있는, 주석이 추가된 응답이 생성될 당시의 에이전트의 버전

주석을 다는 에이전트 상호 작용과 동일한 추적 컨텍스트 내에서 평가 이벤트를 내보내야 합니다(동일한 추적 ID 및 스팬 ID 사용). 이 상관 관계는 주석이 포털의 올바른 추적에 표시되도록 합니다.

실행 가능한 전체 예제는 sample_human_evaluations.py 참조하세요.

추적 페이지에서 주석 보기

포털에서 또는 프로그래밍 방식으로 주석을 추가한 후 추적 세부 정보 페이지에 표시됩니다.

  1. Foundry 프로젝트를 열고 추적으로 이동합니다.
  2. 주석이 있는 추적을 선택합니다.
  3. 추적 세부 정보 페이지에서 주석 아이콘이 주석이 추가된 범위 옆에 표시됩니다. 엄지 손가락 위로 아이콘은 긍정적인 피드백을 나타내고 엄지 손가락 아래 아이콘은 부정적인 피드백을 나타냅니다.
  4. 주석을 마우스로 가리키면 원본(builder 또는 end_user) 평가 이름 및 타임스탬프를 포함한 메타데이터를 볼 수 있습니다.

추적 목록 보기에서 주석은 간략하게 표시됩니다. 가장 최근의 주석만 인라인으로 표시되며, 추적에 주석이 여러 개 있는 경우에는 "+X more" 표시기로 추가 주석이 있음을 알립니다. 추적을 선택하여 모든 주석을 표시합니다.

주석으로 추적 필터링

추적 목록은 다음을 통해 필터링할 수 있습니다.

  • 평가 유형(gen_ai.evaluation.name): 값은 "task_completion"입니다.
  • 점수 값 또는 레이블(gen_ai.evaluation.score.value, gen_ai.evaluation.score.label): 예를 들어, 비추천 평가가 있는 추적만 표시합니다.
  • 원본 (microsoft.gen_ai.human_evaluation.source): 작성기 주석만 표시하거나 최종 사용자 피드백만 표시합니다.

이러한 필터 차원은 기존 추적 필터(시간 범위, 에이전트, 상태, 모델)와 함께 표시됩니다.

Application Insights의 쿼리 주석

모든 주석은 Azure Monitor/Application Insights에 게시되고 원래 추적에 연결됩니다. KQL(Kusto Query Language)을 사용하여 주석을 쿼리하여 피드백 패턴을 분석하거나 대시보드를 빌드하거나 경고를 설정할 수 있습니다.

원본 및 일별 피드백 요약

customEvents
| where name == "gen_ai.evaluation.result"
| extend
    eval_name = tostring(customDimensions["task_completion"]),
    score = todouble(customDimensions["gen_ai.evaluation.score.value"]),
    label = tostring(customDimensions["gen_ai.evaluation.score.label"]),
    eval_source = tostring(customDimensions["microsoft.gen_ai.human_evaluation.source"]),
    trace_id = tostring(customDimensions["trace_id"])
| where eval_source in ("builder", "end_user")
| summarize
    thumbs_up = countif(score == 1.0),
    thumbs_down = countif(score == 0.0),
    total = count()
  by eval_source, bin(timestamp, 1d)
| order by timestamp desc

부정적인 피드백을 사용하여 추적 찾기

customEvents
| where name == "gen_ai.evaluation.result"
| extend
    eval_name = tostring(customDimensions["task_completion"]),
    score = todouble(customDimensions["gen_ai.evaluation.score.value"]),
    eval_source = tostring(customDimensions["microsoft.gen_ai.human_evaluation.source"]),
    explanation = tostring(customDimensions["gen_ai.evaluation.explanation"]),
    trace_id = tostring(customDimensions["trace_id"])
| where score == 0.0
| project timestamp, trace_id, eval_name, eval_source, explanation
| order by timestamp desc

주석 작성 문제 해결

증상 확인
추적을 볼 수 있지만 권한 부여 오류로 빌더 어노테이션 저장이 실패합니다. 저장을 별도의 쓰기 작업으로 처리하십시오. 연결된 Application Insights 리소스, 쓰기에 사용되는 ID(엔터티) 및 연결 인증 모드를 확인합니다. 다른 읽기 권한자 역할을 일반적인 해결 방법으로 추가하지 마세요.
프로그래밍 방식 주석은 401 또는 403을 반환합니다 애플리케이션이 예상 Application Insights 리소스에 원격 분석을 보내는지 확인합니다. Microsoft Entra 인증된 수집의 경우 해당 리소스에서 원격 분석을 내보내는 ID에 모니터링 메트릭 게시자를 부여합니다.
애플리케이션에서 성공을 보고하지만 주석이 표시되지 않습니다. 평가 이벤트가 원래 추적 및 범위 컨텍스트를 사용하고, 추적과 동일한 Application Insights 리소스로 전송되었으며, 수집이 완료되었는지 확인합니다.
주석이 잘못된 트레이스에 표시됨 operation_Id, operation_ParentId, gen_ai.response.id를 이벤트를 내보내기 전에 확인합니다.

관련 콘텐츠

  • 에 마지막으로 업데이트됨