Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Kohandatud funktsioonid (funktsioonide kutsumine)

Õppetund 11 / 16 Värskendatud 30. juuli 2026 Arendajatele
Sellel lehel
  1. Ühenda Grok oma teenustega
  2. Kuidas see toimib
  3. Funktsiooni deklareerimine
  4. Funktsioonikutse vastuvõtmine
  5. Tulemuse tagastamine
  6. Parimad tavad kirjelduste koostamisel
  7. Veakäsitlus
  8. Peamised punktid

Ühenda Grok oma teenustega

Serveripoolsed tööriistad (web_search, x_search, code_interpreter) on kasulikud, kuid piirduvad xAI teenustega. Kohandatud function tööriistadega saad ühendada Groki mis tahes API või teenusega oma taristus.

Kuidas see toimib

Funktsioonide kutsumine järgib kolmeastmelist tsüklit:

  1. Deklareerimine: Kirjeldad oma funktsioone (nimi, kirjeldus, parameetrid) päringus
  2. Kutsumine: Mudel genereerib funktsioonikutse sobivate argumentidega ja peatab genereerimise
  3. Tulemus: Sinu kood käivitab funktsiooni, seejärel saadad tulemuse mudelile tagasi, et see saaks vormistada oma vastuse

Funktsiooni deklareerimine

{
  "model": "grok-4.20-0309-reasoning",
  "input": "Broneeri mulle laud kahele täna õhtul kell 20.00.",
  "tools": [{
    "type": "function",
    "name": "book_restaurant",
    "description": "Broneerib laua restoranis",
    "parameters": {
      "type": "object",
      "properties": {
        "restaurant_name": {
          "type": "string",
          "description": "Restorani nimi"
        },
        "date": {
          "type": "string",
          "description": "Kuupäev formaadis YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "description": "Kellaaeg formaadis HH:MM"
        },
        "guests": {
          "type": "integer",
          "description": "Külaliste arv"
        }
      },
      "required": ["date", "time", "guests"]
    }
  }]
}

Iga funktsiooni ja parameetri kirjeldus on ülioluline. Mudel kasutab neid otsustamaks, millal funktsiooni kutsuda ja kuidas argumendid täita.

Funktsioonikutse vastuvõtmine

Kui mudel otsustab sinu funktsiooni kutsuda, sisaldab vastus elementi function_call:

{
  "id": "resp-xyz789",
  "status": "completed",
  "output": [{
    "type": "function_call",
    "name": "book_restaurant",
    "arguments": "{\"date\": \"2026-04-03\", \"time\": \"20:00\", \"guests\": 2}",
    "call_id": "call-abc123"
  }]
}

Väli arguments on JSON-string, mille pead parsima. call_id identifitseerib seda konkreetset kutset.

Tulemuse tagastamine

Pärast funktsiooni käivitamist oma koodis tagasta tulemus:

import json

# 1. Esmane päring
response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Milline on ilm Pariisis?",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Toob praeguse ilmateate",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"]
        }
    }]
)

# 2. Kontrolli, kas mudel tahab funktsiooni kutsuda
for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)

        # 3. Käivita oma funktsioon
        weather_data = get_weather_from_api(args["city"])

        # 4. Tagasta tulemus mudelile
        final = client.responses.create(
            model="grok-4.20-0309-reasoning",
            input=[{
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(weather_data)
            }],
            previous_response_id=response.id
        )
        print(final.output[0].content[0].text)

Parimad tavad kirjelduste koostamisel

Mudel tugineb funktsioonide mõistmisel kirjeldustele. Ole täpne:

{
  "name": "search_products",
  "description": "Otsib tooteid e-kaubanduse kataloogist. Tagastab 10 parimat tulemust, sorteerituna asjakohasuse järgi. Toetab otsingut nime, kategooria või hinnavahemiku järgi.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Otsingusõnad (toote nimi, bränd, märksõna)"
      },
      "category": {
        "type": "string",
        "enum": ["electronics", "clothing", "home", "sports"],
        "description": "Toote kategooria filtreerimiseks"
      },
      "max_price": {
        "type": "number",
        "description": "Maksimaalne hind eurodes"
      }
    },
    "required": ["query"]
  }
}

Kasuta eelmääratud väärtuste jaoks enum, iga parameetri jaoks üksikasjalikku description ja märgi ainult hädavajalikud parameetrid kui required.

Veakäsitlus

Kui sinu funktsioon ebaõnnestub, tagasta viga tulemusena:

try:
    result = call_external_api(args)
    output = json.dumps(result)
except Exception as e:
    output = json.dumps({"error": str(e)})

final = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input=[{
        "type": "function_call_output",
        "call_id": call_id,
        "output": output
    }],
    previous_response_id=response.id
)

Mudel tõlgendab viga ja saab oma vastust ümber sõnastada või proovida teistsugust lähenemist.

Peamised punktid

  • Kohandatud funktsioonid ühendavad Groki sinu enda teenustega
  • Tsükkel on: deklareeri, võta kutse vastu, käivita, tagasta tulemus
  • Funktsiooni ja parameetrite kirjeldused juhivad mudeli valikut
  • Väli arguments on JSON-string, mille pead kliendipoolselt parsima
  • Tagasta vead tulemustena, et mudel saaks kohaneda