Salt la conținutul principal
Română— Alege o limbă
Meniu

Funcții personalizate (apel de funcții)

Lecția 11 din 16 Actualizată 30 iulie 2026 Dezvoltator
Pe această pagină
  1. Conectați Grok la propriile servicii
  2. Cum funcționează
  3. Declararea unei funcții
  4. Recepcionarea apelului de funcție
  5. Returnarea rezultatului
  6. Cele mai bune practici pentru descrieri
  7. Gestionarea erorilor
  8. Puncte cheie

Conectați Grok la propriile servicii

Instrumentele server (web_search, x_search, code_interpreter) sunt utile, dar limitate la serviciile xAI. Cu instrumente personalizate de tip function, puteți conecta Grok la orice API sau serviciu din infrastructura dumneavoastră.

Cum funcționează

Apelul de funcții urmează un ciclu în trei pași:

  1. Declarare: Descrieți funcțiile dumneavoastră (nume, descriere, parametri) în cerere.
  2. Apel: Modelul generează un apel de funcție cu argumentele adecvate și întrerupe generarea.
  3. Rezultat: Codul dumneavoastră execută funcția, apoi trimiteți rezultatul înapoi modelului pentru a-i permite să formuleze răspunsul.

Declararea unei funcții

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

Descrierea fiecărei funcții și a fiecărui parametru este crucială. Modelul le utilizează pentru a decide când să apeleze funcția și cum să completeze argumentele.

Recepcionarea apelului de funcție

Când modelul decide să apeleze funcția dumneavoastră, răspunsul conține un element 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"
  }]
}

Câmpul arguments este un șir JSON pe care trebuie să îl analizați (parse). Câmpul call_id identifică acest apel specific.

Returnarea rezultatului

După executarea funcției în codul dumneavoastră, returnați rezultatul:

import json

# 1. Cererea inițială
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. Verificați dacă modelul dorește să apeleze o funcție
for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)

        # 3. Executați funcția dumneavoastră
        weather_data = get_weather_from_api(args["city"])

        # 4. Returnați rezultatul modelului
        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)

Cele mai bune practici pentru descrieri

Modelul se bazează pe descrieri pentru a înțelege funcțiile dumneavoastră. Fiți preciși:

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

Utilizați enum pentru valori predefinite, o description detaliată pentru fiecare parametru și marcați ca required doar parametrii esențiali.

Gestionarea erorilor

Dacă funcția dumneavoastră eșuează, returnați eroarea ca rezultat:

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
)

Modelul interpretează eroarea și poate reformula răspunsul sau poate încerca o abordare diferită.

Puncte cheie

  • Funcțiile personalizate conectează Grok la propriile dumneavoastră servicii.
  • Ciclul este: declarați, recepționați apelul, executați, returnați rezultatul.
  • Descrierile funcțiilor și ale parametrilor ghidează alegerea modelului.
  • Câmpul arguments este un șir JSON de analizat (parse) la nivelul clientului.
  • Returnați erorile ca rezultate pentru a permite modelului să se adapteze.