AI Prompt Engineering · Lekcja

Schematy narzędzi i funkcji

Schematy na potrzeby wywoływania funkcji

Schematy narzędzi i funkcji to bezpłatna lekcja AI Prompt Engineering na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej AI Prompt Engineering, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs AI Prompt Engineering zawiera 4 lekcji w sumie.

Narzędzia to schematy i intencja

Wywoływanie funkcji pozwala modelowi zażądać od kodu wykonania działania. Każde narzędzie deklaruje nazwę, opis (określający, kiedy go używać) oraz JSON Schema parametrów.

Model nigdy nie wykonuje kodu; emituje ustrukturyzowane żądanie wywołania, które środowisko uruchomieniowe przekazuje do wykonania. To schemat sprawia, że argumenty można sparsować.

Anatomia definicji narzędzia

Definicja narzędzia to deklaracja możliwości opakowana w schemat.

{
  'type': 'function',
  'function': {
    'name': 'get_weather',
    'description': 'Get current weather for a city. Use when the user asks about weather.',
    'parameters': {
      'type': 'object',
      'properties': {
        'city': {'type': 'string'},
        'units': {'type': 'string', 'enum': ['celsius', 'fahrenheit']}
      },
      'required': ['city', 'units'],
      'additionalProperties': False
    }
  }
}

Opis decyduje o wyborze

Gdy dostępnych jest wiele narzędzi, model wybiera przede wszystkim na podstawie opisu. Należy pisać opisy jako reguły decyzyjne:

Należy określić, kiedy używać narzędzia, a kiedy nie.
Należy odróżnić je od podobnych narzędzi.
Należy wymienić wymagania wstępne.

Błędne opisy częściej prowadzą do wyboru niewłaściwego narzędzia niż błędne schematy do błędów argumentów.

Pętla wywołanie–wykonanie–zwrot

Wywoływanie funkcji przebiega w wielu turach. Model emituje wywołanie, aplikacja je wykonuje, dołącza wynik, a model kontynuuje działanie.

resp = client.chat.completions.create(model='gpt-4o', messages=msgs, tools=tools)
call = resp.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)
result = dispatch(call.function.name, args)
msgs.append(resp.choices[0].message)
msgs.append({'role': 'tool', 'tool_call_id': call.id,
             'content': json.dumps(result)})
# call the model again to continue with the tool result

Równoległe wywołania narzędzi

Nowoczesne modele mogą żądać wielu wywołań narzędzi w jednej turze, gdy działania są niezależne. Środowisko uruchomieniowe powinno iterować po wszystkich tool_calls, wykonywać je (najlepiej współbieżnie) i zwracać po jednej wiadomości narzędzia dla każdego tool_call_id.

Nie należy nigdy zakładać pojedynczego wywołania; zawsze należy iterować.

for call in resp.choices[0].message.tool_calls:
    args = json.loads(call.function.arguments)
    result = dispatch(call.function.name, args)
    msgs.append({'role': 'tool', 'tool_call_id': call.id,
                 'content': json.dumps(result)})

Wymuszanie i ograniczanie użycia narzędzi

Wybór można kontrolować za pomocą tool_choice:

auto — model decyduje.
required — model musi wywołać jakieś narzędzie.
{name: ...} — należy wymusić konkretne narzędzie.
none — należy wyłączyć narzędzia na tę turę.

Wymuszenie konkretnego narzędzia zamienia wywoływanie funkcji w czystą ekstrakcję strukturalną.

client.chat.completions.create(
    model='gpt-4o', messages=msgs, tools=tools,
    tool_choice={'type': 'function', 'function': {'name': 'get_weather'}}
)

Weryfikowanie argumentów przed wykonaniem

Nawet w przypadku ścisłych schematów argumenty narzędzia należy traktować jako niezaufane dane wejściowe. Przed uzyskaniem dostępu do rzeczywistych systemów (baz danych, płatności, usuwania plików) należy ponownie zweryfikować je względem schematu i zastosować reguły biznesowe.

def dispatch(name, args):
    schema = TOOLS[name]['function']['parameters']
    jsonschema.validate(args, schema)   # defense in depth
    if name == 'refund' and args['amount'] > MAX_AUTO_REFUND:
        return {'error': 'requires human approval'}
    return HANDLERS[name](**args)

Błędy narzędzi są częścią protokołu

Gdy narzędzie zawiedzie, należy zwrócić ustrukturyzowany błąd jako wynik narzędzia zamiast zgłaszać wyjątek. Model może wtedy przeprosić, ponowić próbę z poprawionymi argumentami albo wybrać inne narzędzie.

Błędy powinny ułatwiać działanie: należy zawrzeć w nich przyczynę oraz, jeśli jest to bezpieczne, wskazówkę dotyczącą rozwiązania problemu.

{'status': 'error',
 'code': 'CITY_NOT_FOUND',
 'message': 'No city named Xyz. Ask the user to clarify the city.'}

Ograniczanie powierzchni narzędzi

Kilkadziesiąt narzędzi pogarsza trafność wyboru i zwiększa koszt tokenów (schemat każdego narzędzia znajduje się w kontekście w każdej turze). Sposoby ograniczenia tego problemu:

Należy grupować powiązane działania za jednym narzędziem, używając enumu action.
Należy dynamicznie udostępniać tylko narzędzia istotne dla bieżącego stanu.
Należy stosować przestrzenie nazw, aby ograniczyć niejasności między podobnymi narzędziami.

Wzmacnianie schematu na potrzeby efektów ubocznych

W przypadku działań destrukcyjnych należy uwzględnić zabezpieczenia już w samym schemacie: wymagać jawnego pola potwierdzenia, ograniczać zakresy i zamiast dowolnych identyfikatorów tekstowych używać wartości wyliczeniowych lub wzorców poddawanych walidacji.

{
  'name': 'delete_records',
  'parameters': {
    'type': 'object',
    'properties': {
      'table': {'type': 'string', 'enum': ['logs', 'temp_cache']},
      'confirm': {'type': 'boolean'},
      'max_rows': {'type': 'integer', 'minimum': 1, 'maximum': 1000}
    },
    'required': ['table', 'confirm', 'max_rows'],
    'additionalProperties': False
  }
}

Testowanie definicji narzędzi

Wybór narzędzia należy traktować jako mierzalne zachowanie. Należy zbudować zestaw ewaluacyjny promptów przypisanych do oczekiwanego narzędzia i argumentów, a następnie sprawdzać, czy model dokonuje właściwego wyboru. Po zmianie brzmienia opisów lub dodaniu nowych narzędzi należy śledzić regresje.

cases = [
  {'prompt': 'Whats it like in Paris?', 'expect_tool': 'get_weather'},
  {'prompt': 'Convert 10 USD to EUR', 'expect_tool': 'fx_convert'}
]
for c in cases:
    assert run(c['prompt']).tool_name == c['expect_tool']

Szybki test

Model emituje dwa niezależne wywołania tool_calls w jednej turze asystenta. Co musi zrobić środowisko uruchomieniowe?

Podsumowanie

Schematy narzędzi i funkcji w praktyce:

Opisy wpływają na wybór, a schematy zapewniają argumenty, które można analizować.
Należy iterować po wszystkich wywołaniach tool_calls i obsługiwać wykonywanie równoległe.
Zachowanie należy kontrolować za pomocą tool_choice; w przypadku samego wyodrębniania danych należy wymusić użycie narzędzia.
Należy ponownie walidować argumenty i zwracać ustrukturyzowane błędy.
Należy ograniczać liczbę narzędzi i wzmacniać zabezpieczenia działań destrukcyjnych.

Następnie: pętle naprawy i walidacji na wypadek, gdy wynik nadal jest nieprawidłowy.

Często zadawane pytania

Czy lekcja „Schematy narzędzi i funkcji” jest bezpłatna?

Tak — pełny tekst „Schematy narzędzi i funkcji” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu AI Prompt Engineering, przejdź na CoddyKit PRO. Kurs AI Prompt Engineering zawiera 4 lekcji w sumie.

Co nauczysz się w „Schematy narzędzi i funkcji”?

Schematy na potrzeby wywoływania funkcji Ćwiczysz AI Prompt Engineering z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć AI Prompt Engineering?

Nie wymagamy żadnego doświadczenia. AI Prompt Engineering w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.

Ile czasu zajmuje lekcja „Schematy narzędzi i funkcji”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji AI Prompt Engineering?

Tak. Każda lekcja AI Prompt Engineering zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

Dlaczego warto używać ustrukturyzowanych danych wyjściowych
JSON Schema w promptach
Schematy narzędzi i funkcji
Pętle naprawy i walidacji

← Powrót do AI Prompt Engineering