Przejdź do głównej treści
Polski— Wybierz język
Menu

Definiowanie funkcji za pomocą JSON Schema

Lekcja 3 z 14 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Kontrakt między Twoim kodem a modelem
  2. Anatomia specyfikacji narzędzia
  3. Obsługiwane typy JSON Schema
  4. Pełny przykład: dwie uzupełniające się funkcje
  5. Parametry obowiązkowe a opcjonalne
  6. Najlepsze praktyki dotyczące opisów
  7. Kluczowe wnioski

Kontrakt między Twoim kodem a modelem

Aby model Mistral mógł wywołać Twoje funkcje, musi wiedzieć, co istnieje i jak z tego korzystać. Tę rolę pełni JSON Schema: ustandaryzowany format opisujący każdą funkcję – jej nazwę, działanie, oczekiwane parametry oraz to, które z nich są obowiązkowe.

Pamiętaj przez całą tę lekcję o jednej rzeczy: model nigdy nie widzi Twojego kodu Python. Widzi tylko tę specyfikację. Jeśli Twoja funkcja poprawnie obsługuje identyfikatory zapisane małymi literami, ale schema tego nie określa, model zignoruje tę możliwość. Im precyzyjniejsza i lepiej udokumentowana jest Twoja schema, tym dokładniejsze będą generowane argumenty.

Anatomia specyfikacji narzędzia

Każde narzędzie wysyłane do API Mistral ma taką samą strukturę:

tool = {
    "type": "function",
    "function": {
        "name": "function_name",
        "description": "Clear description of what the function does",
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parameter description"
                },
                "param2": {
                    "type": "integer",
                    "description": "Parameter description"
                }
            },
            "required": ["param1"]
        }
    }
}
PoleRola
typeZawsze "function" (inne typy mogą pojawić się w przyszłości)
function.nameDokładna nazwa Twojej funkcji Python – to właśnie ją model zwraca w tool_calls
function.descriptionJasne zdanie pomagające modelowi wybrać właściwą funkcję
function.parametersObiekt JSON Schema opisujący oczekiwane parametry
requiredLista obowiązkowych parametrów

Obsługiwane typy JSON Schema

Słownictwo typów dostępne do opisywania parametrów jest celowo ograniczone, a każdy typ inaczej kieruje modelem. enum w szczególności robi więcej niż tylko dokumentuje: zamyka drzwi przed zmyślonymi wartościami.

# String — dowolny tekst lub ograniczony
{"type": "string", "description": "Transaction ID"}

# String z enum — ograniczone wartości
{"type": "string", "enum": ["asc", "desc"], "description": "Sort order"}

# Integer — liczba całkowita
{"type": "integer", "description": "Number of results to return"}

# Number — liczba dziesiętna
{"type": "number", "description": "Amount in euros"}

# Boolean — prawda/fałsz
{"type": "boolean", "description": "Include canceled transactions"}

# Array — lista wartości
{
    "type": "array",
    "items": {"type": "string"},
    "description": "List of transaction IDs"
}

# Object — zagnieżdżony obiekt
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Shipping address"
}

Wyraźnie rozróżniaj integer od number: kwota w euro, taka jak 125,50, wymaga typu number, podczas gdy liczba wyników do zwrócenia to integer. Zadeklarowanie kwoty jako integer spowoduje, że model ją zaokrągli.

Pełny przykład: dwie uzupełniające się funkcje

Oto realistyczny przykład z dwiema funkcjami związanymi z płatnościami, inspirowany oficjalną dokumentacją Mistral:

tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment (paid, pending, failed) "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Retrieves the date when a payment was made "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

Obie funkcje oczekują dokładnie tego samego parametru, transaction_id, jednak model musi wybrać między nimi. Ten wybór opiera się wyłącznie na opisie funkcji. Pytanie „Czy ta płatność przeszła?“ mapuje się na retrieve_payment_status"; „Kiedy to było?“ mapuje się na retrieve_payment_date`. Gdybyś napisał dwa niejasne, wymienne opisy, model myliłby się w połowie przypadków – i obwiniałbyś model, podczas gdy wina leży po stronie schema.

Parametry obowiązkowe a opcjonalne

Rozróżnienie między parametrami obowiązkowymi a opcjonalnymi decyduje o tym, co model może pominąć.

{
    "type": "function",
    "function": {
        "name": "search_transactions",
        "description": "Searches for transactions based on various criteria",
        "parameters": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "enum": ["paid", "pending", "failed"],
                    "description": "Filter by payment status"
                },
                "date_from": {
                    "type": "string",
                    "description": "Start date in YYYY-MM-DD format"
                },
                "date_to": {
                    "type": "string",
                    "description": "End date in YYYY-MM-DD format"
                },
                "min_amount": {
                    "type": "number",
                    "description": "Minimum amount in euros"
                }
            },
            "required": ["status"]
        }
    }
}

Tutaj tylko status jest wymagany; pozostałe parametry są uwzględniane tylko wtedy, gdy użytkownik o nich wspomni. Porównaj dwa sformułowania. Dla zapytania „Pokaż mi nieudane płatności“ model generuje po prostu {"status": "failed"}. Dla zapytania „Pokaż mi nieudane płatności od marca 2026“ samodzielnie dodaje date_from i date_to. Gdyby uczynienie tych dat obowiązkowymi, zepsułoby pierwsze zapytanie, co gorsza, zmusiłoby model do zmyślenia zakresu dat.

Najlepsze praktyki dotyczące opisów

Jakość opisów bezpośrednio wpływa na dokładność modelu. Poniższe kontrprzykłady są bardziej pouczające niż jakakolwiek abstrakcyjna reguła.

# Źle — zbyt ogólnie
{"description": "Retrieves data"}

# Dobrze — precyzyjnie i z kontekstem
{"description": "Retrieves the status of a payment (paid, pending, failed) "
                "based on the unique transaction ID"}

# Źle — brak opisu parametru
{"transaction_id": {"type": "string"}}

# Dobrze — opis z przykładem
{"transaction_id": {
    "type": "string",
    "description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}

Dobry opis w jednym zdaniu stwierdza, co robi funkcja, określa oczekiwany format dla każdego parametru i podaje przykład, gdy format nie jest oczywisty – T1001 jest lepsze niż „ID transakcji“. Gdy możliwe wartości są ograniczone, nie opisuj ich prozą: zadeklaruj je za pomocą enum. To jedyny sposób, aby stały się wiążące.

Kluczowe wnioski

  • JSON Schema to kontrakt między Twoim kodem a modelem – opisuje Twoje funkcje bez ujawniania kodu
  • Każde narzędzie posiada name, description oraz typowane parameters
  • Obsługiwane typy to string, integer, number, boolean, array i object
  • Lista required odróżnia parametry obowiązkowe od opcjonalnych
  • Precyzyjne opisy z przykładami znacząco poprawiają dokładność modelu