> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-1917.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 피드백 수집 및 어노테이션 활용

> UI와 SDK를 통해 LLM 애플리케이션의 피드백을 수집하고 분석

LLM 애플리케이션을 효율적으로 평가하려면 피드백을 수집하고 분석할 수 있는 강력한 도구가 필요합니다. W\&B Weave는 통합 피드백 시스템을 제공하므로, 사용자는 UI에서 직접 또는 SDK를 통해 프로그래밍 방식으로 call 피드백을 제공할 수 있습니다. 이모지 반응, 텍스트 댓글, 구조화된 데이터 등 다양한 피드백 유형을 지원하므로 팀은 다음과 같은 작업을 수행할 수 있습니다:

* 성능 모니터링을 위한 평가 데이터셋을 구축합니다.
* LLM 콘텐츠 문제를 효과적으로 파악하고 해결합니다.
* 파인튜닝과 같은 고급 작업에 활용할 예시를 수집합니다.

이 가이드에서는 UI와 SDK에서 Weave의 피드백 기능을 사용하는 방법, 피드백을 쿼리하고 관리하는 방법, 그리고 세부 평가를 위한 휴먼 어노테이션을 사용하는 방법을 다룹니다.

* [UI에서 피드백 제공하기](#provide-feedback-in-the-ui)
* [SDK를 통해 피드백 제공하기](#provide-feedback-through-the-sdk)
* [휴먼 어노테이션 추가하기](#add-human-annotations)

<div id="provide-feedback-in-the-ui">
  ## UI에서 피드백 남기기
</div>

Weave UI에서는 [Call details panel](#from-the-call-details-panel)이나 [아이콘 사용](#use-the-icons)을 통해 피드백을 추가하고 확인할 수 있습니다.

<div id="from-the-call-details-panel">
  ### Call details 패널에서
</div>

1. Weave 프로젝트 사이드바에서 **트레이스**로 이동합니다.
2. 피드백을 추가하려는 Call 행을 찾습니다.
3. 링크된 Trace 이름을 클릭해 트레이스 트리와 Call details 패널을 엽니다.
4. Call details 탭 바에서 **Feedback**을 선택합니다.
5. 피드백을 추가, 조회 또는 삭제합니다.
   * Call details 피드백 뷰의 오른쪽 상단에 있는 아이콘을 사용해 *피드백을 추가하고 조회합니다*.
   * *Call details 피드백 테이블에서 피드백을 조회하고 삭제합니다.* 해당 피드백 행의 가장 오른쪽 열에 있는 휴지통 아이콘을 클릭해 피드백을 삭제합니다.

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-1917/P5YFMliBxN9ub2uu/weave/guides/tracking/imgs/feedback_tab.png?fit=max&auto=format&n=P5YFMliBxN9ub2uu&q=85&s=94f515ba114a4e016b3808b7535fc336" alt="Call details의 Feedback 탭 스크린샷" width="1266" height="548" data-path="weave/guides/tracking/imgs/feedback_tab.png" />
</Frame>

<div id="use-the-feedback-icons">
  ### 피드백 아이콘 사용
</div>

트레이스 table와 개별 Call details panel에 있는 아이콘을 사용해 반응을 추가하거나 제거하고 메모를 추가할 수 있습니다.

* *트레이스 table*: **트레이스** table의 해당 행에 있는 **Feedback** 열에 있습니다.
* *Call details panel*: 각 Call details panel의 오른쪽 상단에 있습니다.

반응을 추가하려면 다음과 같이 하세요.

1. 이모지 아이콘을 클릭합니다.
2. thumbs up 또는 thumbs down을 추가하거나, 더 많은 이모지를 사용하려면 **+** 아이콘을 클릭합니다.

반응을 제거하려면 다음과 같이 하세요.

1. 제거하려는 이모지 반응 위에 마우스를 올립니다.
2. 해당 반응을 클릭해 제거합니다.

> [Call details panel의 **Feedback** 열](#from-the-call-details-panel)에서도 피드백을 삭제할 수 있습니다.

댓글을 추가하려면 다음과 같이 하세요.

1. 댓글 말풍선 아이콘을 클릭합니다.
2. 텍스트 상자에 메모를 입력합니다. 피드백 메모의 최대 글자 수는 1024자입니다.
3. 메모를 저장하려면 **Enter** 키를 누릅니다. 메모는 추가로 더 입력할 수 있습니다.

<Warning>
  피드백 메모의 최대 글자 수는 1024자입니다. 메모가 이 제한을 초과하면 생성되지 않습니다.
</Warning>

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-1917/P5YFMliBxN9ub2uu/weave/guides/tracking/imgs/feedback_calls.png?fit=max&auto=format&n=P5YFMliBxN9ub2uu&q=85&s=9356c674ddd40f11d33c6a9fbdae8db0" alt="피드백 열이 있는 calls 그리드 스크린샷" width="3170" height="1589" data-path="weave/guides/tracking/imgs/feedback_calls.png" />
</Frame>

<div id="provide-feedback-through-the-sdk">
  ## SDK를 통해 피드백 제공
</div>

UI의 Call details panel에 있는 **Use** 탭에서 피드백용 SDK 사용 예시를 찾을 수 있습니다.

Weave Python SDK를 사용하면 call에 대한 피드백을 프로그래밍 방식으로 [추가](/ko/weave/reference/python-sdk/trace/feedback#method-add)하거나, [삭제](/ko/weave/reference/python-sdk/trace/feedback#method-purge)하거나, [조회](/ko/weave/reference/python-sdk/trace/weave_client#method-get_feedback)할 수 있습니다. TypeScript SDK는 현재 피드백 기능을 지원하지 않습니다.

<div id="query-a-projects-feedback">
  ### 프로젝트 피드백 쿼리하기
</div>

SDK를 사용해 Weave 프로젝트의 피드백을 쿼리할 수 있습니다. SDK는 다음과 같은 피드백 쿼리 오퍼레이션을 지원합니다.

* `client.get_feedback()`: 프로젝트의 모든 피드백을 반환합니다.
* `client.get_feedback("<feedback_uuid>")`: `<feedback_uuid>`로 지정한 특정 피드백 객체를 컬렉션으로 반환합니다.
* `client.get_feedback(reaction="<reaction_type>")`: 특정 반응 유형에 해당하는 모든 피드백 객체를 반환합니다.

`client.get_feedback()`에서는 각 피드백 객체에 대해 다음과 같은 추가 정보도 조회할 수 있습니다.

* `id`: 피드백 객체 ID입니다.
* `created_at`: 피드백 객체의 생성 시간 정보입니다.
* `feedback_type`: 피드백 유형입니다(reaction, note, 맞춤형).
* `payload`: 피드백 페이로드입니다.

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    client = weave.init('intro-example')

    # 프로젝트의 모든 피드백 조회
    all_feedback = client.get_feedback()

    # ID로 특정 피드백 객체를 가져옵니다.
    # API는 컬렉션을 반환하며, 여기에 포함된 항목은 최대 1개일 것으로 예상됩니다.
    one_feedback = client.get_feedback("<feedback_uuid>")[0]

    # 특정 반응 유형의 모든 피드백 객체를 찾습니다. offset과 limit를 지정할 수 있습니다.
    thumbs_up = client.get_feedback(reaction="👍", limit=10)

    # 조회 후 개별 피드백 객체의 세부 정보를 확인합니다.
    for f in client.get_feedback():
        print(f.id)
        print(f.created_at)
        print(f.feedback_type)
        print(f.payload)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    이 기능은 아직 TypeScript에서 사용할 수 없습니다.
    ```
  </Tab>
</Tabs>

<div id="add-feedback-to-a-call">
  ### Call에 피드백 추가
</div>

Call의 UUID를 사용해 Call에 피드백을 추가할 수 있습니다. UUID로 특정 Call을 조회하려면 [Call 실행 중 또는 실행 후에 UUID를 조회](#retrieve-the-call-uuid)하세요. SDK는 Call에 피드백을 추가하기 위해 다음 오퍼레이션을 지원합니다.

* `call.feedback.add_reaction("<reaction_type>")`: 👍와 같은 지원되는 `<reaction_types>`(이모지) 중 하나를 추가합니다.
* `call.feedback.add_note("<note>")`: 노트를 추가합니다.
* `call.feedback.add("<label>", <object>)`: `<label>`로 지정한 맞춤형 피드백 `<object>`를 추가합니다.

<Warning>
  피드백 노트의 최대 글자 수는 1024자입니다. 노트가 이 제한을 초과하면 생성되지 않습니다.
</Warning>

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    client = weave.init('intro-example')

    call = client.get_call("<call_uuid>")

    # 이모지 반응 추가
    call.feedback.add_reaction("👍")

    # 노트 추가
    call.feedback.add_note("this is a note")

    # 맞춤형 키/값 쌍 추가
    # 첫 번째 인자는 사용자 정의 "type" 문자열입니다.
    # 피드백은 JSON으로 직렬화할 수 있어야 하며, 직렬화된 크기는 1KB 미만이어야 합니다.
    call.feedback.add("correctness", { "value": 5 })
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    이 기능은 아직 TypeScript에서 사용할 수 없습니다.
    ```
  </Tab>
</Tabs>

<div id="retrieve-the-call-uuid">
  #### Call UUID 조회
</div>

Call 직후에 바로 피드백을 추가해야 하는 경우, Call 실행 중이나 실행 후에 프로그래밍 방식으로 Call UUID를 조회할 수 있습니다.

<div id="during-call-execution">
  ##### Call 실행 중
</div>

Call 실행 중에 UUID를 조회하려면 현재 Call을 가져온 다음 ID를 반환하세요.

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}

    import weave
    weave.init("uuid")

    @weave.op()
    def simple_operation(input_value):
        # 단순한 오퍼레이션 수행
        output = f"Processed {input_value}"
        # 현재 call ID 조회
        current_call = weave.require_current_call()
        call_id = current_call.id
        return output, call_id
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    이 기능은 아직 TypeScript에서 사용할 수 없습니다.
    ```
  </Tab>
</Tabs>

<div id="after-call-execution">
  ##### Call 실행 후
</div>

또는 `call()` 방법을 사용해 오퍼레이션을 실행한 뒤 Call ID를 조회할 수 있습니다:

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    weave.init("uuid")

    @weave.op()
    def simple_operation(input_value):
        return f"Processed {input_value}"

    # 오퍼레이션을 실행하고 결과와 call ID를 조회합니다
    result, call = simple_operation.call("example input")
    call_id = call.id
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    이 기능은 아직 TypeScript에서 사용할 수 없습니다.
    ```
  </Tab>
</Tabs>

<div id="delete-feedback-from-a-call">
  ### Call에서 피드백 삭제
</div>

UUID를 지정하면 특정 Call의 피드백을 삭제할 수 있습니다.

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    call.feedback.purge("<feedback_uuid>")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    이 기능은 아직 TypeScript에서 사용할 수 없습니다.
    ```
  </Tab>
</Tabs>

<div id="add-human-annotations">
  ## 휴먼 어노테이션 추가
</div>

휴먼 어노테이션은 Weave UI에서 지원됩니다. 이 기능을 사용하면 트레이스에 피드백으로 추가할, 사람이 직접 입력한 데이터용 맞춤형 필드를 만들 수 있습니다. 휴먼 어노테이션을 작성하려면 먼저 [UI](#create-a-human-annotation-scorer-in-the-ui) 또는 [API](#create-a-human-annotation-scorer-using-the-api)를 사용해 휴먼 어노테이션 스코어러를 만들어야 합니다. 그런 다음 [UI에서 스코어러를 사용해 어노테이션을 작성하고](#use-the-human-annotation-scorer-in-the-ui), [API를 사용해 어노테이션 스코어러를 수정할 수 있습니다](#modify-a-human-annotation-scorer-using-the-api).

<div id="create-a-human-annotation-scorer-in-the-ui">
  ### UI에서 휴먼 어노테이션 스코어러 만들기
</div>

UI에서 휴먼 어노테이션 스코어러를 만들려면 다음 단계를 따르세요.

1. 프로젝트 사이드바에서 **Assets**로 이동합니다.
2. Assets 내비게이션 패널에서 **Scorers**를 클릭합니다.
3. **Scorers** 패널 헤더에서 **New scorer**를 클릭합니다.
4. **Create Scorer** 모달 대화상자에서 다음을 설정합니다.
   * `Scorer type`을 `Human annotation`으로 설정
   * `Name`
   * `Description`
   * 수집할 피드백 유형을 결정하는 `Type`(예: `boolean` 또는 `integer`)
5. **Create scorer**를 클릭합니다. 이제 이 휴먼 어노테이션 스코어러를 사용해 어노테이션을 만들 수 있습니다.

다음 예에서는 human annotator가 LLM이 수집한 문서의 유형을 선택합니다. 따라서 score 설정에서 선택한 `Type`은 가능한 문서 유형이 포함된 `enum`입니다.

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-1917/P5YFMliBxN9ub2uu/weave/guides/tracking/imgs/human-annotation-scorer-form.png?fit=max&auto=format&n=P5YFMliBxN9ub2uu&q=85&s=6cd6348b450e62e810bd224c9c0900a0" alt="Create Scorer 모달 대화상자" width="3454" height="1862" data-path="weave/guides/tracking/imgs/human-annotation-scorer-form.png" />
</Frame>

<div id="use-the-human-annotation-scorer-in-the-ui">
  ### UI에서 휴먼 어노테이션 스코어러 사용하기
</div>

휴먼 어노테이션 스코어러를 생성하면 **트레이스** 페이지에서 사용할 수 있습니다.

scorer를 사용하려면 다음 단계를 따르세요.

1. 프로젝트 사이드바에서 **트레이스**로 이동합니다.

2. human annotation을 추가하려는 Call의 행을 찾습니다.

3. 연결된 Trace 이름을 클릭해 trace tree와 Call details panel을 엽니다.

4. Call details 탭 바의 오른쪽 상단에서 **Show feedback** 버튼을 클릭합니다.

   <img src="https://mintcdn.com/wb-21fd5541-docs-1917/P5YFMliBxN9ub2uu/weave/guides/tracking/imgs/marker-icon.png?fit=max&auto=format&n=P5YFMliBxN9ub2uu&q=85&s=8f5f5d45b498b4b6791a03dc1926f12b" alt="Call 헤더의 마커 아이콘" width="306" height="84" data-path="weave/guides/tracking/imgs/marker-icon.png" />

   사용 가능한 휴먼 어노테이션 스코어러가 추가 **Annotate** 패널에 표시됩니다.

   <img src="https://mintcdn.com/wb-21fd5541-docs-1917/P5YFMliBxN9ub2uu/weave/guides/tracking/imgs/full-feedback-sidebar.png?fit=max&auto=format&n=P5YFMliBxN9ub2uu&q=85&s=4a85f44ee0ed193486872beb550398c4" alt="Human Annotation scorer 피드백 패널" width="3454" height="1862" data-path="weave/guides/tracking/imgs/full-feedback-sidebar.png" />

5. annotation을 입력합니다.

6. **Save**를 클릭합니다.

7. Call details panel 탭 바에서 **Feedback** 탭을 클릭해 Feedback table을 확인합니다. 새 annotation이 테이블에 표시됩니다. 메인 트레이스 table의 **Annotations** 열에서도 어노테이션을 확인할 수 있습니다.

   > 최신 정보를 보려면 트레이스 table을 새로고침하세요.

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-1917/P5YFMliBxN9ub2uu/weave/guides/tracking/imgs/feedback-in-the-table.png?fit=max&auto=format&n=P5YFMliBxN9ub2uu&q=85&s=559b570672581302159aa7a91c4c1736" alt="Traces table의 Human Annotation scorer 피드백" width="3456" height="1569" data-path="weave/guides/tracking/imgs/feedback-in-the-table.png" />
</Frame>

<div id="create-a-human-annotation-scorer-using-the-api">
  ### API를 사용하여 휴먼 어노테이션 스코어러 생성하기
</div>

API를 통해 휴먼 어노테이션 스코어러를 만들 수도 있습니다. 각 scorer는 별도의 객체이며, 각각 독립적으로 생성하고 업데이트할 수 있습니다. 프로그래밍 방식으로 휴먼 어노테이션 스코어러를 만들려면 다음 단계를 따르세요.

1. `weave.flow.annotation_spec`에서 `AnnotationSpec` 클래스를 임포트합니다.
2. `weave`의 `publish`를 사용해 scorer를 생성합니다.

다음 예제에서는 두 개의 scorer를 생성합니다. 첫 번째 scorer인 `Temperature`는 LLM call의 체감 온도를 평가하는 데 사용됩니다. 두 번째 scorer인 `Tone`은 LLM 응답의 어조를 평가하는 데 사용됩니다. 각 scorer는 연관된 객체 ID(`temperature-scorer` 및 `tone-scorer`)와 함께 `save`를 사용해 생성됩니다.

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    from weave.flow.annotation_spec import AnnotationSpec

    client = weave.init("feedback-example")

    spec1 = AnnotationSpec(
      name="Temperature",
      description="The perceived temperature of the llm call",
      field_schema={
        "type": "number",
        "minimum": -1,
        "maximum": 1,
      }
    )
    spec2 = AnnotationSpec(
      name="Tone",
      description="The tone of the llm response",
      field_schema={
        "type": "string",
        "enum": ["Aggressive", "Neutral", "Polite", "N/A"],
      },
    )
    weave.publish(spec1, "temperature-scorer")
    weave.publish(spec2, "tone-scorer")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    이 기능은 아직 TypeScript에서 사용할 수 없습니다.
    ```
  </Tab>
</Tabs>

<div id="modify-a-human-annotation-scorer-using-the-api">
  ### API를 사용해 휴먼 어노테이션 스코어러 수정하기
</div>

[API를 사용해 휴먼 어노테이션 스코어러 생성하기](#create-a-human-annotation-scorer-using-the-api)에서 이어서, 다음 예제에서는 `publish` 시 원래 객체 ID(`temperature-scorer`)를 사용해 `Temperature` scorer의 업데이트된 버전을 생성합니다. 그 결과 모든 버전의 이력이 포함된 업데이트된 객체가 만들어집니다.

> **Human annotations** 아래의 **Scorers** 탭에서 휴먼 어노테이션 스코어러 객체의 이력을 확인할 수 있습니다.

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    from weave.flow.annotation_spec import AnnotationSpec

    client = weave.init("feedback-example")

    # scorer의 새 버전 생성
    spec1 = AnnotationSpec(
      name="Temperature",
      description="The perceived temperature of the llm call",
      field_schema={
        "type": "integer",  # <<- 유형을 integer로 변경
        "minimum": -1,
        "maximum": 1,
      }
    )
    weave.publish(spec1, "temperature-scorer")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    이 기능은 아직 TypeScript에서 사용할 수 없습니다.
    ```
  </Tab>
</Tabs>

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-1917/P5YFMliBxN9ub2uu/weave/guides/tracking/imgs/human-annotation-scorer-history.png?fit=max&auto=format&n=P5YFMliBxN9ub2uu&q=85&s=3bfbf120896ec8fdb19c509a1724ac24" alt="Human Annotation scorer 이력" width="2686" height="1434" data-path="weave/guides/tracking/imgs/human-annotation-scorer-history.png" />
</Frame>

<div id="use-a-human-annotation-scorer-using-the-api">
  ### API를 사용해 휴먼 어노테이션 스코어러 사용하기
</div>

feedback API를 사용하면 특별한 형식의 name과 `annotation_ref` 필드를 지정해 휴먼 어노테이션 스코어러를 사용할 수 있습니다. `annotation_spec_ref`는 UI에서 적절한 탭을 선택해 획득하거나, `AnnotationSpec`를 생성하는 동안 획득할 수 있습니다.

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave

    client = weave.init("feedback-example")

    call = client.get_call("<call_id>")
    annotation_spec = weave.ref("<annotation_spec_ref_uri>")

    call.feedback.add(
      feedback_type="wandb.annotation." + annotation_spec.name,
      payload={"value": 1},
      annotation_ref=annotation_spec.uri(),
    )
    ```
  </Tab>
</Tabs>