Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Mukautetut funktiot (funktiokutsut)

Oppitunti 11 / 16 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Yhdistä Grok omiin palveluihisi
  2. Miten se toimii
  3. Määritä funktio
  4. Vastaanota funktiokutsu
  5. Palauta tulos
  6. Parhaat käytännöt kuvauksissa
  7. Virheenkäsittely
  8. Keskeiset asiat

Yhdistä Grok omiin palveluihisi

Palvelintyökalut (web_search, x_search, code_interpreter) ovat käteviä, mutta rajoittuvat xAI:n palveluihin. Mukautettujen function-työkalujen avulla voit yhdistää Grokin mihin tahansa infrastruktuurisi API:hin tai palveluun.

Miten se toimii

Funktiokutsu noudattaa kolmivaiheista sykliä:

  1. Määrittely: Kuvaat funktiosi (nimi, kuvaus, parametrit) pyynnössä
  2. Kutsu: Malli generoi funktiokutsun sopivilla argumenteilla ja keskeyttää generoinnin
  3. Tulos: Koodisi suorittaa funktion, minkä jälkeen lähetät tuloksen takaisin mallille, jotta se voi muotoilla vastauksensa

Määritä funktio

{
  "model": "grok-4.20-0309-reasoning",
  "input": "Book me a table for 2 people tonight at 8 PM.",
  "tools": [{
    "type": "function",
    "name": "book_restaurant",
    "description": "Books a table at a restaurant",
    "parameters": {
      "type": "object",
      "properties": {
        "restaurant_name": {
          "type": "string",
          "description": "Restaurant name"
        },
        "date": {
          "type": "string",
          "description": "Date in YYYY-MM-DD format"
        },
        "time": {
          "type": "string",
          "description": "Time in HH:MM format"
        },
        "guests": {
          "type": "integer",
          "description": "Number of guests"
        }
      },
      "required": ["date", "time", "guests"]
    }
  }]
}

Jokaisen funktion ja parametrin kuvaus on ratkaisevan tärkeä. Malli käyttää niitä päättääkseen, milloin funktiota kutsutaan ja miten argumentit täytetään.

Vastaanota funktiokutsu

Kun malli päättää kutsua funktiotasi, vastaus sisältää function_call-kohteen:

{
  "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"
  }]
}

arguments-kenttä on JSON-merkkijono, joka sinun on jäsennettävä. call_id tunnistaa tämän tietyn kutsun.

Palauta tulos

Suoritettuasi funktion koodissasi, palauta tulos:

import json

# 1. Alkuperäinen pyyntö
response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What's the weather like in Paris?",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Retrieves current weather",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"]
        }
    }]
)

# 2. Tarkista, haluaako malli kutsua funktion
for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)

        # 3. Suorita funktiosi
        weather_data = get_weather_from_api(args["city"])

        # 4. Palauta tulos mallille
        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)

Parhaat käytännöt kuvauksissa

Malli luottaa kuvauksiin ymmärtääkseen funktiosi. Ole tarkka:

{
  "name": "search_products",
  "description": "Searches for products in the e-commerce catalog. Returns the top 10 results sorted by relevance. Supports search by name, category, or price range.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search terms (product name, brand, keyword)"
      },
      "category": {
        "type": "string",
        "enum": ["electronics", "clothing", "home", "sports"],
        "description": "Product category to filter"
      },
      "max_price": {
        "type": "number",
        "description": "Maximum price in euros"
      }
    },
    "required": ["query"]
  }
}

Käytä enum-arvoja ennalta määritellyille arvoille, yksityiskohtaista description-kuvausta jokaiselle parametrille ja merkitse vain olennaiset parametrit required-kenttään.

Virheenkäsittely

Jos funktiosi epäonnistuu, palauta virhe tuloksena:

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
)

Malli tulkitsee virheen ja voi muotoilla vastauksensa uudelleen tai kokeilla eri lähestymistapaa.

Keskeiset asiat

  • Mukautetut funktiot yhdistävät Grokin omiin palveluihisi
  • Sykli on: määritä, vastaanota kutsu, suorita, palauta tulos
  • Funktio- ja parametrkuvaukset ohjaavat mallin valintaa
  • arguments-kenttä on JSON-merkkijono, joka jäsennetään asiakaspuolella
  • Palauta virheet tuloksina, jotta malli pystyy sopeutumaan