Schemat wejściowy oceny agenta (MLflow 2)

2025-06-23

Ważne

Na tej stronie opisano użycie wersji ewaluacyjnej 0.22 agenta za pomocą platformy MLflow 2. Databricks zaleca korzystanie z MLflow 3, który jest zintegrowany z Agent Evaluation >1.0. W MLflow 3 interfejsy API oceny agentów są teraz częścią pakietu mlflow.

Aby uzyskać informacje na temat tego tematu, zobacz Tworzenie zestawów danych oceny MLflow.

W tym artykule wyjaśniono schemat danych wejściowych wymagany przez ocenę agenta w celu oceny jakości, kosztów i opóźnień aplikacji.

Podczas fazy rozwoju ocena odbywa się w trybie offline, a zestaw ewaluacyjny jest wymaganym wejściem do Ewaluacji Agenta.
Gdy aplikacja jest w środowisku produkcyjnym, wszystkie dane wejściowe do Oceny Agenta pochodzą z tabel wnioskowania lub dzienników produkcyjnych.

Schemat wejściowy jest identyczny zarówno w przypadku ocen online, jak i offline.

Aby uzyskać ogólne informacje na temat zestawów oceny, zobacz Zestawy ewaluacyjne (MLflow 2).

Schemat wejściowy oceny

W poniższej tabeli przedstawiono schemat wejściowy systemu oceny agenta. Dwie ostatnie kolumny tabeli odnoszą się do sposobu podania danych wejściowych do wywołania mlflow.evaluate(). Aby uzyskać szczegółowe informacje, zobacz Zapewnianie danych wejściowych do przebiegu oceny.

Kolumna	Typ danych	opis	Aplikacja przekazana jako argument wejściowy	Wcześniej wygenerowane dane wyjściowe
identyfikator_żądania	sznurek	Unikatowy identyfikator żądania.	Opcjonalnie	Opcjonalnie
żądanie	Zobacz Schemat dla żądania.	Dane wejściowe aplikacji do oceny: pytanie lub zapytanie użytkownika. Na przykład `{'messages': [{"role": "user", "content": "What is RAG"}]}` lub "Co to jest RAG?". Gdy `request` zostanie podany jako ciąg, zostanie on przekształcony na `messages` przed przekazaniem go do agenta.	Wymagane	Wymagane
odpowiedź	Zobacz Schemat dla odpowiedzi.	Odpowiedź wygenerowana przez ocenianą aplikację.	Generowane przez ocenę agenta	Opcjonalny. Jeśli nie zostanie podany, to zostanie wywnioskowany ze śledzenia. Albo `response` albo `trace` jest wymagany.
oczekiwane_fakty	tablica ciągów znaków	Lista faktów, które są oczekiwane w danych wyjściowych modelu. Zobacz `expected_facts` wskazówki.	Opcjonalnie	Opcjonalnie
oczekiwana_odpowiedź	sznurek	Zweryfikowana (poprawna) odpowiedź na żądanie wejściowe. Zobacz `expected_response` wskazówki.	Opcjonalnie	Opcjonalnie
Wytyczne	`guidelines` wytyczne	Nazwany słownik lub lista wytycznych, z którymi dane wyjściowe modelu powinny się zgadzać. Zobacz `guidelines` wskazówki.	Opcjonalnie	Opcjonalnie
oczekiwany_uzyskany_kontekst	tablica	Tablica obiektów zawierających oczekiwany kontekst pobrany dla żądania (jeśli aplikacja zawiera krok pobierania). schemat tablicy	Opcjonalnie	Opcjonalnie
pobrany_kontekst	tablica	Wyniki pobierania wygenerowane przez program retriever w ocenianej aplikacji. Jeśli w aplikacji znajduje się wiele kroków pobierania, jest to wynik pobierania z ostatniego kroku (chronologicznie w ścieżce). schemat tablicy	Generowane przez ocenę agenta	Opcjonalny. Jeśli nie podano, pochodzi z podanego śladu.
ślad	Ciąg JSON śledzenia MLflow	Śledzenie MLflow wykonania aplikacji w odniesieniu do odpowiedniego żądania.	Generowane przez ocenę agenta	Opcjonalny. Albo `response` albo `trace` jest wymagany.

`expected_facts` Wytyczne

Pole expected_facts określa listę faktów, które powinny pojawić się w dowolnej poprawnej odpowiedzi modelu dla określonego żądania wejściowego. Oznacza to, że odpowiedź modelu jest uważana za poprawną, jeśli zawiera te fakty, niezależnie od sposobu wyrażenia odpowiedzi.

Uwzględnienie tylko wymaganych faktów i pominięcie tych, które nie są ściśle wymagane w odpowiedzi, pozwala ocenie agenta na dostarczenie bardziej solidnego wskaźnika jakości wyników.

Można określić co najwyżej jeden z elementów expected_facts i expected_response. Jeśli określisz oba te elementy, zostanie zgłoszony błąd. Databricks zaleca użycie metody expected_facts, gdyż stanowi ona bardziej szczegółową wskazówkę, która pozwala na skuteczniejsze ocenianie jakości generowanych odpowiedzi podczas oceny agentów.

`guidelines` Wytyczne

Pole guidelines określa określone wytyczne, z którymi musi być zgodna każda poprawna odpowiedź modelu. guidelines można wyrazić w dwóch formatach:

Lista wytycznych (List[str]) zawiera jeden zestaw wytycznych.
Nazwane wytyczne (Dict[str, List[str]]) przypisują nazwę wytycznych do tablicy wytycznych związanych z tą nazwą. Określone wytyczne wymagają databricks-agents >= 0.16.0.

Wytyczne mogą odnosić się do różnych cech odpowiedzi, w tym elementów stylistycznych lub związanych z zawartością. Aby uzyskać najbardziej niezawodny sygnał dotyczący przestrzegania wytycznych, usługa Databricks zaleca używanie następującego języka:

"Odpowiedź musi ..."
"Odpowiedź nie może ..."
"Odpowiedź może opcjonalnie ..."

W szczególności należy bezpośrednio odwołać się do żądania i odpowiedzi i pozostawić jak najmniej niejednoznaczności, jak to możliwe w wytycznych. Aby uzyskać wytyczne dotyczące całego zestawu oceny, takie jak zapewnienie, że odpowiedzi mają profesjonalny ton lub są zawsze w języku angielskim, użyj parametru global_guidelines w konfiguracji ewaluatora w następujący sposób:

eval_set = [
    {
        "request": "What is the difference between reduceByKey and groupByKey in Spark?",
        "response": "reduceByKey aggregates data before shuffling, whereas groupByKey shuffles all data, making reduceByKey more efficient.",
        # Note: You can also just pass an array to `guidelines`.
        "guidelines": {
            "english": ["The response must be in English"],
            "clarity": ["The response must be clear, coherent, and concise"],
        }
    }
]

mlflow.evaluate(
    data=pd.DataFrame(eval_set),
    model_type="databricks-agent",
    evaluator_config={
        "databricks-agent": {
            # Note: You can also just pass an array to `guidelines`.
            "global_guidelines": {
                "english": ["The response must be in English"],
                "clarity": ["The response must be clear, coherent, and concise"],
            }
        }
    }
)

`expected_response` Wytyczne

Pole expected_response zawiera w pełni sformułowaną odpowiedź, która reprezentuje odwołanie do poprawnych odpowiedzi modelu. Oznacza to, że odpowiedź modelu jest uważana za poprawną, jeśli pasuje do zawartości informacji w pliku expected_response. W przeciwieństwie do tego, expected_facts zawiera wyłącznie fakty, które są wymagane do pojawienia się w poprawnej odpowiedzi i nie stanowi w pełni sformułowanej odpowiedzi referencyjnej.

Podobnie jak expected_facts, expected_response powinna zawierać tylko minimalny zestaw faktów wymaganych do poprawnej odpowiedzi. Uwzględnienie tylko niezbędnych informacji i pominięcie tych, które nie są ściśle wymagane w odpowiedzi, pozwala ocenie agenta dostarczyć bardziej solidny sygnał dotyczący jakości wyników.

schemat żądania

Schemat żądania może być jednym z następujących elementów:

Dowolny słownik z możliwością serializacji (na przykład Dict[str, Any])
Jeśli agent obsługuje schemat uzupełniania czatu OpenAI, możesz przekazać zwykły ciąg. Ten format obsługuje tylko konwersacje jednokrotne. Zwykłe ciągi są konwertowane do formatu messages, zanim są przekazane do agenta. Na przykład zwykły ciąg "What is MLflow?" jest konwertowany na {"messages": [{"role": "user", "content": "What is MLflow?"}]} przed przekazaniem do agenta.

Należy pamiętać, że wbudowani sędziowie najlepiej współpracują z dowolnym formatem korzystając z schematu uzupełniania czatu OpenAI . Schemat uzupełniania czatu OpenAI musi mieć jako parametr messages tablicę obiektów. Pole messages może kodować pełną konwersację.

Poniższy przykład przedstawia kilka możliwych opcji w tej samej kolumnie request zestawu danych oceny:

import pandas as pd

data = {
  "request": [

      # Plain string. Plain strings are transformed to the `messages` format before being passed to your agent.
      "What is the difference between reduceByKey and groupByKey in Spark?",

      # OpenAI chat completion schema. Use the `messages` field for a single- or multi-turn chat.
      {
          "messages": [
              {
                  "role": "user",
                  "content": "How can you minimize data shuffling in Spark?"
              }
          ]
      },

      # SplitChatMessagesRequest. Use the `query` and `history` fields for a single- or multi-turn chat.
      {
          "query": "Explain broadcast variables in Spark. How do they enhance performance?",
          "history": [
              {
                  "role": "user",
                  "content": "What are broadcast variables?"
              },
              {
                  "role": "assistant",
                  "content": "Broadcast variables allow the programmer to keep a read-only variable cached on each machine."
              }
          ]
      },

      # Arbitrary format. These must be JSON-serializable and are passed directly to your agent.
      {
        "message_history": [
            {
                "user_0": "What are broadcast variables?",
                "assistant_0": "Broadcast variables allow the programmer to keep a read-only variable cached on each machine.",
            }
        ],
        "last_user_request": "How can you minimize data shuffling in Spark?"
      },
  ],

  "expected_response": [
    "expected response for first question",
    "expected response for second question",
    "expected response for third question",
    "expected response for fourth question",
  ]
}

eval_dataset = pd.DataFrame(data)

schemat na potrzeby odpowiedzi

Schemat odpowiedzi podobny do schematu żądania może być jednym z następujących elementów:

Dowolny słownik z możliwością serializacji (na przykład Dict[str, Any]).
Jeśli agent obsługuje schemat uzupełniania czatu OpenAI, możesz przekazać zwykły ciąg. Ten format obsługuje tylko konwersacje jednokrotne. Zwykłe ciągi są konwertowane na format choices. Na przykład zwykły ciąg "MLFlow is a framework." jest konwertowany na {"choices": [{"message": {"content": "MLFlow is a framework."}}]}.

Schemat tablic w danych wejściowych oceny

Schemat tablic expected_retrieved_context i retrieved_context przedstawiono w poniższej tabeli:

Kolumna	Typ danych	opis	Aplikacja przekazana jako argument wejściowy	Wcześniej wygenerowane dane wyjściowe
treść	sznurek	Zawartość pobranego kontekstu. Ciąg w dowolnym formacie, takim jak HTML, zwykły tekst lub Markdown.	Opcjonalnie	Opcjonalnie
doc_uri	sznurek	Unikatowy identyfikator (URI) dokumentu nadrzędnego, z którego pochodzi fragment.	Wymagane	Wymagane

Obliczone metryki

Kolumny w poniższej tabeli wskazują dane zawarte w danych wejściowych, a ✓ wskazuje, że metryka jest obsługiwana po podaniu tych danych.

Aby uzyskać szczegółowe informacje na temat miary tych metryk, zobacz Jak jakość, koszt i opóźnienie są oceniane przez ocenę agenta (MLflow 2).

Metryki obliczeniowe	`request`	`request` i `expected_response`	`request`, `expected_response`, `expected_retrieved_context`i `guidelines`	`request` i `expected_retrieved_context`	`request` i `guidelines`
`response/llm_judged/relevance_to_query/rating`	✓	✓	✓
`response/llm_judged/safety/rating`	✓	✓	✓
`response/llm_judged/groundedness/rating`	✓	✓	✓
`retrieval/llm_judged/chunk_relevance_precision`	✓	✓	✓
`agent/total_token_count`	✓	✓	✓
`agent/input_token_count`	✓	✓	✓
`agent/output_token_count`	✓	✓	✓
`response/llm_judged/correctness/rating`		✓	✓
`retrieval/llm_judged/context_sufficiency/rating`		✓	✓
`retrieval/ground_truth/document_recall`			✓	✓
`response/llm_judged/guideline_adherence/rating`			✓		✓

Udostępnij za pośrednictwem

Schemat wejściowy oceny agenta (MLflow 2)

Schemat wejściowy oceny

expected_facts Wytyczne

guidelines Wytyczne

expected_response Wytyczne