AI 애플리케이션 평가하기¶

시나리오 1: 함수 추적하기¶

추적해야 하는 함수 앞에 @instrument() 를 추가할 수 있습니다. 이렇게 하면 함수에 대한 입력, 출력(반환 값), 실행 지연 시간이 자동으로 캡처됩니다. 예를 들어, 다음 코드는 입력 쿼리와 최종 응답을 자동으로 캡처하는 answer_query 함수를 추적하는 방법을 보여줍니다.

@instrument()
def answer_query(self, query: str) -> str:
    context_str = self.retrieve_context(query)
    return self.generate_completion(query, context_str)

시나리오 2: 특정 스팬 유형으로 함수 추적하기¶

스팬 유형은 함수의 특성을 지정하고 추적의 가독성과 이해도를 향상시킵니다. 예를 들어, RAG 애플리케이션에서 검색 서비스(또는 검색기)에 대해 스팬 유형을 “RETRIEVAL”로 지정하고 LLM 추론 호출에 대해 스팬 유형을 “GENERATION”로 지정할 수 있습니다. 지원되는 스팬 유형은 다음과 같습니다.

• RETRIEVAL: 검색 또는 검색 함수를 위한 스팬 유형

• GENERATION: LLM 에서 모델 추론 호출 시 스팬 유형

• RECORD_ROOT: 애플리케이션의 주요 함수에 대한 스팬 유형

@instrument() 로 스팬 유형을 지정하지 않으면 기본적으로 UNKNOWN 스팬 유형이 지정됩니다. 스팬 특성을 사용하려면 Python 애플리케이션에 다음 가져오기를 추가하십시오.

from trulens.otel.semconv.trace import SpanAttributes

다음 코드 스니펫은 RAG 애플리케이션 추적을 보여줍니다. 스팬 유형은 항상 SpanAttributes.SpanType 으로 접두사를 붙여야 합니다.

@instrument(span_type=SpanAttributes.SpanType.RETRIEVAL)
def retrieve_context(self, query: str) -> list:
    """
    Retrieve relevant text from vector store.
    """
    return self.retrieve(query)

@instrument(span_type=SpanAttributes.SpanType.GENERATION)
def generate_completion(self, query: str, context_str: list) -> str:
    """
    Generate answer from context by calling an LLM.
    """
    return response

@instrument(span_type=SpanAttributes.SpanType.RECORD_ROOT)
def answer_query(self, query: str) -> str:
    context_str = self.retrieve_context(query)
    return self.generate_completion(query, context_str)

시나리오 3: 함수 추적 및 평가 계산하기¶

스팬 유형을 제공하는 것 외에도 메트릭을 계산하려면 애플리케이션에서 관련 매개 변수를 스팬 특성에 할당해야 합니다. 예를 들어, RAG 애플리케이션에서 컨텍스트 관련성을 계산하려면 관련 쿼리 및 검색 결과 매개 변수를 각각 적절한 특성 RETRIEVAL.QUERY_TEXT 및 RETRIEVAL.RETRIEVED_CONTEXTS 에 할당해야 합니다. 각 개별 메트릭을 계산하는 데 필요한 특성은 메트릭 페이지에서 확인할 수 있습니다.

각 스팬 유형에 대해 지원되는 스팬 특성은 다음과 같습니다.

• RECORD_ROOT: INPUT, OUTPUT, GROUND_TRUTH_OUTPUT

• RETRIEVAL: QUERY_TEXT, RETRIEVED_CONTEXTS

• GENERATION: 없음

스팬 특성을 사용하려면 Python 애플리케이션에 다음 가져오기를 추가해야 합니다.

from trulens.otel.semconv.trace import SpanAttributes

다음 코드 스니펫은 검색 서비스에 대한 컨텍스트 관련성을 계산하는 예제를 제공합니다. 특성은 항상 SpanAttributes.<스팬 유형>.<특성 이름> (예: SpanAttributes.RETRIEVAL.QUERY_TEXT)의 형식을 따라야 합니다.

@instrument(
    span_type=SpanAttributes.SpanType.RETRIEVAL,
    attributes={
        SpanAttributes.RETRIEVAL.QUERY_TEXT: "query",
        SpanAttributes.RETRIEVAL.RETRIEVED_CONTEXTS: "return",
    }
)
def retrieve_context(self, query: str) -> list:
    """
    Retrieve relevant text from vector store.
    """
    return self.retrieve(query)

앞의 예제에서 는 retrieve_context() 에 대한 입력 매개 변수를 나타내고 return 은 반환 값을 나타냅니다. 이는 컨텍스트 관련성을 계산하기 위해 RETRIEVAL.QUERY_TEXT 및 RETRIEVAL.RETRIEVED_CONTEXTS 특성에 할당됩니다.

Run Configuration¶

실행은 RunConfig 에서 생성됩니다

run_config = RunConfig(
    run_name=run_name,
    description="desc",
    label="custom tag useful for grouping comparable runs",
    source_type="DATAFRAME",
    dataset_name="My test dataframe name",
    dataset_spec={
        "RETRIEVAL.QUERY_TEXT": "user_query_field",
        "RECORD_ROOT.INPUT": "user_query_field",
        "RECORD_ROOT.GROUND_TRUTH_OUTPUT": "golden_answer_field",
    },
    llm_judge_name: "mistral-large2"
)

• run_name: str: 실행 이름은 동일한 TruApp 내에서 고유해야 합니다.

• description: str (선택 사항): 실행에 대한 문자열 설명

• label: str (선택 사항): 함께 실행을 그룹화하는 데 사용되는 레이블

• source_type: str: 데이터 세트의 소스를 지정합니다. Python 데이터프레임의 경우 DATAFRAME, Snowflake 계정의 사용자 테이블의 경우 TABLE 일 수 있습니다.

• dataset_name: str: source_type이 DATAFRAME 인 경우 사용자가 지정한 임의의 이름. 또는 현재 컨텍스트(데이터베이스 및 스키마)에서 사용자 계정의 유효한 Snowflake 테이블 이름 또는 “database.schema.table_name” 형식의 Snowflake 정규화된 이름입니다.

• dataset_spec: Dict[str, str]: 지원되는 스팬 특성을 데이터 프레임 또는 테이블의 사용자 열 이름에 매핑하는 사전입니다. 허용되는 키는 데이터 세트 페이지에 지정된 대로 스팬 특성이며 허용되는 값은 사용자가 지정한 데이터 프레임 또는 테이블의 열 이름입니다. 예를 들어, 위의 실행 구성 예제에서 “golden_answer_field”는 유효한 열 이름이어야 합니다

• llm_judge_name: str (선택 사항): LLM 기반 메트릭 계산 시 LLM 평가자로 사용할 이름입니다. 지원되는 평가자는 모델 페이지를 참조하십시오. 지정하지 않으면 기본값은 llama3.1-70b 입니다.

run = tru_app.add_run(run_config=run_config)

요청 매개 변수:

• run_config: RunConfig 에는 실행을 위한 구성이 들어 있습니다.

Retrieve Run¶

실행을 검색합니다.

run = tru_app.get_run(run_name=run_name)

요청 매개 변수:

• run_name: str: 실행의 이름

View Run 메타데이터¶

실행에 대한 세부 정보를 설명합니다.

run.describe()

Invoke Run¶

run.start() 함수를 사용하여 실행을 호출할 수 있습니다. 실행 구성에 지정된 데이터 세트에서 입력을 읽고, 각 입력에 대해 애플리케이션을 호출하고, 추적을 생성하고, Snowflake 계정에 저장할 정보를 수집합니다. run.start() 는 데이터 세트의 모든 입력에 대해 애플리케이션이 호출되고 수집이 완료되거나 시간 초과가 될 때까지 차단되는 호출입니다.

run.start()  # if source_type is "TABLE"

run.start(input_df=user_input_df)  # if source_type is "DATAFRAME"

요청 매개 변수:

• input_df: DataFrame (선택 사항): SDK 의 Pandas 데이터 프레임입니다. 실행 구성에서 source_type이 DATAFRAME 으로 지정된 경우 이 필드는 필수입니다. Source_type이 TABLE 인 경우 이 필드는 필수가 아닙니다.

Compute metrics¶

애플리케이션이 호출되고 모든 추적이 수집된 후 run.compute_metrics() 을 사용하여 메트릭 계산을 시작할 수 있습니다. 실행 상태가 INVOCATION_IN_PROGRESS 인 한 계산을 시작할 수 없습니다. 상태가 INVOCATION_COMPLETED 또는 INVOCATION_PARTIALLY_COMPLETED 인 경우 run.compute_metrics() 을 시작할 수 있습니다. run.compute_metrics() 은 비동기식 비차단 함수입니다. 서로 다른 메트릭 세트를 사용하여 동일한 실행에서 compute_metrics 을 여러 번 호출할 수 있으며, 각 호출은 새로운 계산 작업을 트리거합니다. 한 번 계산된 메트릭은 동일한 실행에 대해 다시 계산할 수 없습니다.

run.compute_metrics(metrics=[
    "coherence",
    "answer_relevance",
    "groundedness",
    "context_relevance",
    "correctness",
])

요청 매개 변수:

• metrics: List[str]: 메트릭에 나열된 메트릭의 문자열 이름 목록입니다. 메트릭의 이름은 스네이크 케이스로 지정해야 합니다. 즉, 컨텍스트 관련성은 context_relevance 로 지정해야 합니다.

Check Run Status¶

실행이 진행된 후 실행 상태를 확인할 수 있습니다. 상태 목록은 실행 상태 섹션에 있습니다.

run.get_status()

Cancel Run¶

run.cancel() 을 사용하여 기존 실행을 취소할 수 있습니다. 이 작업은 실행 상태 및 메타데이터 필드를 포함하여 향후 실행에 대한 모든 업데이트를 방지합니다.

run.cancel()

Delete Run¶

run.delete() 를 사용하여 기존 실행을 삭제할 수 있습니다. 이 작업은 실행과 관련된 메타데이터를 삭제하며 평가 결과에 액세스할 수 없습니다. 그러나 실행의 일부로 생성된 추적 및 평가는 삭제되지 않고 계속 저장됩니다. 평가 및 추적의 저장소 및 삭제에 대한 자세한 내용은 Observability 데이터 섹션을 참조하십시오.

run.delete()

애플리케이션에 대한 목록 실행¶

list_runs() 함수를 사용하여 특정 TruApp 애플리케이션 오브젝트에 해당하는 사용 가능한 모든 실행 목록을 확인할 수 있습니다.

tru_app.list_runs()

응답:

tru_app 에서 기본으로 생성된 모든 실행 목록을 반환합니다.