Avalie os aplicativos AI¶

Cenário 1: rastreie uma função¶

Você pode adicionar @instrument() antes da função que precisa rastrear. Isso captura automaticamente as entradas da função, as saídas (valores de retorno) e a latência da execução. Por exemplo, o código a seguir demonstra o rastreamento de uma função answer_query que captura automaticamente a consulta de entrada e a resposta final:

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

Cenário 2: rastreie uma função com um tipo específico de intervalo¶

Um tipo de extensão especifica a natureza da função e melhora a legibilidade e a compreensão dos rastros. Por exemplo, em um aplicativo RAG, você pode especificar o tipo de intervalo como “RETRIEVAL” para o serviço de busca (ou mecanismo de recuperação) e especificar o tipo de intervalo como “GENERATION” para a chamada de inferência LLM. Os seguintes tipos de span são compatíveis:

• RETRIEVAL: tipo de span para funções de recuperação ou pesquisa

• GENERATION: tipo de intervalo para chamadas de inferência de modelo de um LLM

• RECORD_ROOT: tipo de span para a função principal em seu aplicativo

Se você não especificar um tipo de span com @instrument(), um tipo de span UNKNOWN será atribuído por padrão. Para usar os atributos de span, adicione a seguinte importação ao seu aplicativo Python.

from trulens.otel.semconv.trace import SpanAttributes

O trecho de código a seguir demonstra o rastreamento de um aplicativo RAG. O tipo de extensão deve ser sempre prefixado com 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)

Cenário 3: rastreie uma função e calcule avaliações¶

Além de fornecer tipos de abrangência, você deve atribuir parâmetros relevantes em seu aplicativo aos atributos de abrangência para calcular as métricas. Por exemplo, para calcular a relevância do contexto em um aplicativo RAG, você deve atribuir a consulta relevante e o parâmetro de resultados de recuperação aos atributos apropriados RETRIEVAL.QUERY_TEXT e RETRIEVAL.RETRIEVED_CONTEXTS, respectivamente. Os atributos necessários para calcular cada métrica individual podem ser encontrados na página Métricas.

Os seguintes atributos de span são compatíveis para cada tipo de span:

• RECORD_ROOT: INPUT, OUTPUT, GROUND_TRUTH_OUTPUT

• RETRIEVAL: QUERY_TEXT, RETRIEVED_CONTEXTS

• GENERATION: nenhum

Para usar os atributos de span, você precisa adicionar a seguinte importação ao seu aplicativo Python.

from trulens.otel.semconv.trace import SpanAttributes

O trecho de código a seguir fornece um exemplo para calcular a relevância do contexto para um serviço de recuperação. Os atributos devem sempre seguir o formato SpanAttributes.<tipo de span>.<nome de atributo> (por exemplo, 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)

No exemplo anterior, query representa o parâmetro de entrada para retrieve_context() e return representa o valor retornado. Eles são designados aos atributos RETRIEVAL.QUERY_TEXT e RETRIEVAL.RETRIEVED_CONTEXTS para calcular a relevância do contexto.

Configuração de execução¶

Uma execução é criada a partir de um 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: nome da execução; deve ser exclusivo no mesmo TruApp

• description: str (opcional): descrição de cadeia de caracteres da execução

• label: str (opcional): rótulo usado para agrupar as execuções

• source_type: str: especifica a fonte do conjunto de dados. Pode ser DATAFRAME para um dataframe Python ou TABLE para uma tabela de usuários na conta Snowflake.

• dataset_name: str: qualquer nome arbitrário especificado pelo usuário se source_type for DATAFRAME. Ou um nome de tabela válido do Snowflake na conta do usuário no contexto atual (banco de dados e esquema) ou um nome totalmente qualificado do Snowflake na forma de “database.schema.table_name”.

• dataset_spec: Dict[str, str]: dicionário que mapeia os atributos do intervalo compatível para os nomes das colunas do usuário no dataframe ou na tabela. As chaves permitidas são atributos do intervalo, conforme especificado na página Conjunto de dados, e os valores permitidos são nomes de colunas no dataframe ou na tabela especificada pelo usuário. Por exemplo, “golden_answer_field” no exemplo de configuração de execução acima deve ser um nome de coluna válido

• llm_judge_name: str (opcional): nome a ser usado como juiz LLM durante o cálculo da métrica com base em LLM. Consulte a página de modelos para ver os juízes compatíveis. Se não for especificado, o valor padrão é llama3.1-70b

run = tru_app.add_run(run_config=run_config)

Parâmetros de solicitação:

• run_config: RunConfig: você pode usar o arquivo de configuração para a execução.

Recupere a execução¶

Recupera a execução.

run = tru_app.get_run(run_name=run_name)

Parâmetros de solicitação:

• run_name: str: nome da execução

Visualize os metadados de execução¶

Descreve os detalhes da execução.

run.describe()

Invoque a execução¶

Você pode invocar a execução usando a função run.start(). Ele lê as entradas do conjunto de dados especificado na configuração de execução, invoca o aplicativo para cada entrada, gera os rastreamentos e ingere as informações para armazenamento em sua conta Snowflake. run.start() é uma chamada de bloqueio até que o aplicativo seja invocado para todas as entradas no conjunto de dados e a ingestão seja concluída ou expirada.

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

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

Parâmetros de solicitação:

• input_df: DataFrame (opcional): é um pandas DataFrame do SDK. Se source_type na configuração de execução for especificado como DATAFRAME, esse campo será obrigatório. Se source_type for TABLE, esse campo não será obrigatório.

Compute as métricas¶

Você pode iniciar os cálculos de métrica usando run.compute_metrics() depois que o aplicativo for chamado e todos os rastreamentos forem ingeridos. Enquanto o status da execução for INVOCATION_IN_PROGRESS, o cálculo não poderá ser iniciado. Quando o status for INVOCATION_COMPLETED ou INVOCATION_PARTIALLY_COMPLETED, run.compute_metrics() poderá ser iniciado. run.compute_metrics() é uma função assíncrona e não bloqueadora. Você pode chamar compute_metrics várias vezes na mesma execução com um conjunto diferente de métricas, e cada chamada acionará um novo trabalho de computação. Observe que as métricas, uma vez computadas, não podem ser computadas novamente para a mesma execução.

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

Parâmetros de solicitação:

• metrics: List[str]: lista de nomes de cadeia de caracteres das métricas listadas em Metrics. O nome das métricas deve ser especificado em snake case, ou seja, a relevância de contexto deve ser especificada como context_relevance.

Verifique o status de execução¶

Você pode verificar o status de execução depois que ela estiver em andamento. A lista de status está na seção Status de execução.

run.get_status()

Cancele a execução¶

Você pode cancelar uma execução existente usando run.cancel(). Essa operação impedirá qualquer atualização futura da execução, incluindo o status da execução e os campos de metadados.

run.cancel()

Exclua a execução¶

Você pode excluir uma execução existente usando run.delete(). Essa operação exclui os metadados associados à execução e os resultados da avaliação não podem ser acessados. No entanto, os rastros e as avaliações gerados como parte das execuções não são excluídos e permanecem armazenados. Consulte a seção Dados de observabilidade para obter mais informações sobre o armazenamento e a exclusão de avaliações e rastreamentos.

run.delete()

Liste as execuções para um aplicativo¶

Você pode ver a lista de todas as execuções disponíveis correspondentes a um objeto específico do aplicativo TruApp usando a função list_runs().

tru_app.list_runs()

Resposta:

Retorne uma lista de todas as execuções criadas em tru_app.