Hakutyökalut: Dynaamiset työkalut
Tällä sivulla
Oppitunti päivitetty 2. marraskuuta 2026 OpenAI:n dokumentaation perusteella: Code Interpreter -työkalu vaatii nyt
container-parametrin (lisätty kaikkiin esimerkkeihin), syöttötekstiosat on tyypitetty muodossainput_text, ja verkkohaku käyttääweb_search-työkalua (web_search_previewon nyt vanhentunut työkalu ilman verkkotunnussuodattimia). Generoidut tiedostot haetaan käyttämällä oppitunnin 10 funktioitafichiers_generesjatelecharger. Lähteet: Code Interpreter · Web search.
Hakutyökalut: Dynaamiset työkalut
Kun sinulla on kymmeniä tai satoja funktioita, niiden kaikkien määrittely jokaisessa pyynnössä muuttuu vastatuottavaksi: malli menettää tarkkuutensa ja kustannukset räjähtävät. Hakutyökalut (Tool Search) ratkaisee tämän ongelman antamalla mallille mahdollisuuden etsiä oikea työkalu indeksoidusta luettelosta.
Suurten työkaluluetteloiden ongelma
Suuren työkaluluettelon kustannukset ovat näkymättömiä kahdella tavalla. Ensinnäkin taloudellisesti: jokainen funktiomääritelmä lähetetään jokaisen pyynnön mukana, mukaan lukien ne yhdeksänkymmentäkahdeksan, joita ei käytetä. Laajassa mittakaavassa tämä ylittää lopulta itse vastausten kustannukset. Toiseksi, ja mikä on vakavampaa, laadullisesti: kun työkaluja on muutama kymmenen ja niiden käyttötarkoitukset menevät päällekkäin, malli tekee huonompia valintoja. Liian monet vaihtoehdot heikentävät päätöksentekoa, tässä kuten muuallakin.
# 5 funktiota = ~500 kontekstitokenia
# 50 funktiota = ~5000 kontekstitokenia
# 200 funktiota = mahdotonta hallita tehokkaasti
# Malli menettää tarkkuutensa, kun funktioita on liikaa
# Se valitsee joskus väärän funktion tai hallusinoi parametreja
Hakutyökalujen käyttöönotto
Hakutyökalut kääntävät logiikan päälaelleen: sen sijaan, että esittelisit kaiken mallille, indeksoit luettelon ja näytät sille vain sen, mikä vastaa nykyistä pyyntöä. Mekanismi perustuu kuvausten semanttiseen hakuun – minkä vuoksi seuraava osio ei ole pelkkää tyylineuvontaa, vaan ehdoton vaatimus järjestelmän toiminnalle.
from openai import OpenAI
client = OpenAI()
# Määrittele suuri määrä funktioita
all_functions = [
{
"type": "function",
"name": "create_invoice",
"description": "Create a new invoice for a customer",
"parameters": {"type": "object", "properties": {"client_id": {"type": "string"}}, "required": ["client_id"]}
},
{
"type": "function",
"name": "cancel_invoice",
"description": "Cancel an existing invoice",
"parameters": {"type": "object", "properties": {"invoice_id": {"type": "string"}}, "required": ["invoice_id"]}
},
# ... kymmeniä muita funktioita
]
# Käytä hakutyökaluja antaaksesi mallin löytää oikean funktion
response = client.responses.create(
model="gpt-5.6-terra",
input="Cancel invoice FAC-2026-0042",
tools=[{
"type": "tool_search",
"tool_search": {
"tools": all_functions
}
}]
)
Malli vastaanottaa kontekstiinsa vain pyyntöä koskevat funktiot, ei koko luetteloa.
Funktioluettelon järjestäminen
Kaksi periaatetta riittää rakentamaan luettelo, joka pysyy selkeänä. Käytä etuliitteitä nimissä toimialan mukaan (crm_, billing_, inventory_): suoritusjäljen lukeminen muuttuu välittömäksi, ja nimien törmäykset katoavat. Anna lisäksi jokaiselle funktiolle selkeä käyttötarkoitus – kaksi funktiota, joiden kuvaukset menevät päällekkäin, tuottavat epävakaita valintoja, tekipä valinnan ihminen tai vektoriengine.
crm_catalog = [
{
"type": "function",
"name": "crm_search_customer",
"description": "Search for a customer in the CRM by name, email, or ID. "
"Use to find information about an existing customer.",
"parameters": {
"type": "object",
"properties": {
"term": {"type": "string", "description": "Search term"},
"field": {"type": "string", "enum": ["name", "email", "id"]}
},
"required": ["term"],
"additionalProperties": False
},
"strict": True
},
{
"type": "function",
"name": "crm_create_customer",
"description": "Create a new customer in the CRM. "
"Use when a customer does not yet exist.",
"parameters": {
"type": "object",
"properties": {
"name": {"type": "string"},
"email": {"type": "string"},
"company": {"type": "string"}
},
"required": ["name", "email", "company"],
"additionalProperties": False
},
"strict": True
}
]
billing_catalog = [
{
"type": "function",
"name": "bill_create_invoice",
"description": "Create an invoice. Requires an existing customer.",
"parameters": {
"type": "object",
"properties": {
"client_id": {"type": "string"},
"lines": {"type": "array", "items": {"type": "object", "properties": {
"description": {"type": "string"},
"amount": {"type": "number"}
}}}
},
"required": ["client_id", "lines"],
"additionalProperties": False
},
"strict": True
}
]
# Yhdistä kaikki luettelot
full_catalog = crm_catalog + billing_catalog
Parhaat käytännöt kuvauksissa
Kirjoita kuvaukset hakua varten, älä dokumentaatiota varten. Haku ”Retrieve customer data” ei koskaan löydy kysymyksellä ”order history” tai ”billing contact details”: käyttäjiesi todella kirjoittamien sanojen on esiinnyttävä indeksoidussa tekstissä. Hyödyllinen kuvaus nimeää käyttötapaukset ja liiketoimintasanaston, ei toteutusyksityiskohtia.
# Huono: liian yleinen
{"name": "get_data", "description": "Retrieve data"}
# Hyvä: spesifi ja sisältää käyttök kontekstin
{
"name": "hr_check_leave_balance",
"description": "Check an employee's leave balance (vacation, personal time, sick leave). "
"Returns remaining days by leave type. "
"Use when an employee asks how many days they have left."
}
# Hyvä: sisältää synonyymejä haun parantamiseksi
{
"name": "acct_reconcile_bank",
"description": "Bank reconciliation: compare accounting entries "
"with bank transactions. Account reconciliation. "
"Use to verify consistency between accounting records "
"and bank statements."
}
Hakutyökalujen yhdistäminen kiinteisiin työkaluihin
Yhdistäminen on tuotantoympäristön vakiotila. Muutama poikkileikkaava työkalu – aika, nykyinen käyttäjä, asiakirjahaku – pysyy määriteltynä pysyvästi, koska ne palvelevat lähes jokaista pyyntöä, kun taas liiketoimintaluettelo pysyy dynaamisena. Tämä pitää kontekstin kevyenä tekemättä mallista jatkuvaa hakua tarpeellisille asioille.
response = client.responses.create(
model="gpt-5.6-terra",
input="Search the web for this month's sales and create the corresponding invoice",
tools=[
# Aina käytettävissä olevat työkalut
{"type": "web_search"},
{"type": "code_interpreter", "container": {"type": "auto"}},
# Dynaaminen luettelo
{
"type": "tool_search",
"tool_search": {
"tools": full_catalog # 200+ funktiota
}
}
]
)
Malli: Monialuejärjestelmä
class MultiDomainSystem:
def __init__(self):
self.client = OpenAI()
self.catalogs = {}
def register_domain(self, name: str, functions: list[dict]):
"""Rekisteröi funktioluettelo toimialalle."""
self.catalogs[name] = functions
def full_catalog(self) -> list[dict]:
"""Yhdistä kaikki luettelot."""
result = []
for functions in self.catalogs.values():
result.extend(functions)
return result
def execute(self, query: str) -> str:
"""Suorita kysely käyttäen hakutyökaluja kaikilla toimialoilla."""
response = self.client.responses.create(
model="gpt-5.6-terra",
input=query,
tools=[{
"type": "tool_search",
"tool_search": {
"tools": self.full_catalog()
}
}]
)
# Käsittele funktiokutsut
for item in response.output:
if item.type == "function_call":
result = self.dispatcher(item.name, item.arguments)
# ... funktiokutsusilmukka
return response.output_text
def dispatcher(self, name: str, arguments: str):
"""Reititä kutsu oikeaan palveluun."""
# Reitityslogiikkasi
pass
# Käyttö
system = MultiDomainSystem()
system.register_domain("crm", crm_catalog)
system.register_domain("billing", billing_catalog)
system.register_domain("hr", hr_catalog)
system.register_domain("support", support_catalog)
# Malli löytää automaattisesti oikean funktion
# satojen mahdollisuuksien joukosta
result = system.execute("How many vacation days does Marie Dupont have left?")
Keskeiset asiat
- Hakutyökalut ratkaisevat suurten funktioluetteloiden ongelman
- Malli vastaanottaa kontekstiinsa vain asiaankuuluvat funktiot
- Rikkaat ja spesifit kuvaukset ovat välttämättömiä tarkkuudelle
- Käytä etuliitteitä funktioissa toimialan mukaan luettavuuden parantamiseksi
- Yhdistä hakutyökalut aina käytettävissä oleviin sisäänrakennettuihin työkaluihin