Combinarea instrumentelor de server și de client
Pe această pagină
Două categorii de instrumente pe aceeași platformă
API-ul Grok distinge două tipuri de instrumente fundamental diferite, în funcție de modul de execuție. Înțelegerea acestei distincții este esențială pentru proiectarea unor arhitecturi robuste.
Instrumente integrate (lato server)
xAI execută aceste instrumente automat pe propriile servere. Dumneavoastră nu gestionați nimic: nu există execuție locală, nici transmitere a rezultatelor. Modelul le apelează și primește rezultatele direct.
| Instrument | Identificator | Descriere |
|---|---|---|
| Web Search | web_search | Căutare web în timp real |
| X Search | x_search | Căutare pe X/Twitter |
| Code Interpreter | code_interpreter | Execuție Python în mediu izolat (sandbox) |
| Collections Search | collections_search | Căutare în documentele încărcate de dumneavoastră |
| Remote MCP | mcp | Conectare la servere MCP externe |
Funcții personalizate (lato client)
Acestea sunt funcțiile dumneavoastră proprii, definite prin mecanismul de „function calling“. Modelul returnează un tool_call, codul dumneavoastră execută funcția, iar dumneavoastră trimiteți înapoi rezultatul. Acesta este mecanismul pe care l-ați învățat în lecțiile anterioare.
Combinarea ambelor tipuri într-o singură cerere
Puterea API-ului Grok constă în capacitatea de a combina instrumentele de server și cele de client într-o singură cerere:
tools = [
# Instrument server — executat automat de xAI
{"type": "web_search"},
# Instrument client — executat de codul dumneavoastră
{
"type": "function",
"function": {
"name": "save_to_database",
"description": "Save information to the database",
"parameters": {
"type": "object",
"properties": {
"key": {"type": "string"},
"value": {"type": "string"}
},
"required": ["key", "value"]
}
}
}
]
Când modelul primește această cerere, el poate:
- Să utilizeze
web_searchpentru a găsi informații (execuție automată lato server) - Să apeleze
save_to_databasepentru a salva rezultatul (returnare către client)
Fluxul hibrid
Comportamentul diferă în funcție de tipul instrumentului:
- Instrument server: modelul apelează instrumentul, xAI îl execută, rezultatul este integrat automat, iar modelul continuă procesul.
- Instrument client: modelul returnează
tool_callcătre client, execuția se oprește și reia doar după ce dumneavoastră trimiteți rezultatul.
Când modelul utilizează ambele tipuri în aceeași cerere, instrumentele de server se execută primele (fără intervenția dumneavoastră). Apoi, dacă modelul are nevoie și de un instrument de client, vă returnează tool_call, având deja integrate în contextul său rezultatele obținute de la instrumentele de server.
Exemple din lumea reală
Căutare web + logică de afaceri
# Utilizatorul întreabă: „Găsește prețul Bitcoin și salvează-l“
# Modelul:
# 1. Apelează web_search pentru a găsi prețul (server, automat)
# 2. Apelează save_price(symbol="BTC", price=68432) (client)
Căutare X + notificare
# „Alertează-mă privind tweet-urile despre produsul nostru de ieri încoace“
# Modelul:
# 1. Apelează x_search pentru a găsi tweet-urile (server)
# 2. Apelează send_notification(count=12, summary="...") (client)
Code Interpreter + stocare
# „Calculează media acestor date și salvează rezultatul“
# Modelul:
# 1. Apelează code_interpreter pentru calcul (server)
# 2. Apelează save_result(key="avg", value="42.5") (client)
Facturarea pentru instrumentele de server
Instrumentele integrate sunt facturate în două moduri:
- Tokeni: consum standard (input + output)
- Invocări: cost fix per apel de instrument
Modelul poate apela mai multe instrumente de server pentru o singură cerere – costurile se acumulează. Rețineți acest aspect când activați web_search: modelul ar putea efectua mai multe căutări pentru a-și rafina rezultatele.
Puncte cheie
- Două tipuri de instrumente: server (automat) și client (function calling)
- Instrumentele de server (
web_search,x_search,code_interpreter) se execută fără intervenția dumneavoastră - Puteți combina ambele tipuri într-o singură cerere
- Instrumentele de server se execută primele, apoi modelul poate apela funcțiile dumneavoastră
- Fiecare invocare a unui instrument de server este facturată (tokeni + cost per apel)
- Citările sunt generate automat pentru datele provenite de la instrumentele de server