Arkkitehtuurit useilla työkaluilla tuotannossa
Tällä sivulla
Päivitetty 2. marraskuuta 2026 OpenAI:n dokumentaation perusteella: Code Interpreter -työkalu vaatii nyt
container-parametrin (lisätty kaikkiin esimerkkeihin), tekstisyötteet 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.
Arkkitehtuurit useilla työkaluilla tuotannossa
Usean työkalun prototyyppi toimii, koska sitä käyttää yksi henkilö, joka tuntee sen rajat ja käynnistää sen uudelleen epäonnistumisen sattuessa. Tuotanto poistaa kaikki kolme ehtoa samanaikaisesti. Kriittiseksi ei nouse vastauksen laatu – se oli jo olemassa – vaan kolme ominaisuutta, joita prototyypistä puuttui: tieto siitä, mitä tapahtui puhelun epäonnistuessa, kyky estää loputon silmukka tyhjentämästä budjettiasi ja mahdollisuus muuttaa toimintaa ilman uudelleenkäyttöönottoa.
Alla olevat mallit ratkaisevat kukin yhden näistä vaatimuksista. Älä otta kaikkia käyttöön kerralla: aloita havainnoitavuudesta, sillä ilman sitä et edes tiedä, mikä muista puuttuu.
Kerrosarkkitehtuuri
Vastuiden erottaminen kerroksiin ei ole arkkitehtonista hienostuneisuutta: se tekee jokaisesta osasta vaihdettavan. Konkreettinen hyöty on se, että voit muuttaa orkestrointia koskematta käyttöliittymään tai lisätä työkalun kirjoittamatta liiketoimintalogiikkaa uudelleen. Alla olevat neljä kerrosta ovat minimaalinen jako, joka kestää käytännössä.
# Kerros 1: Käyttöliittymä - pyynnön vastaanotto
# Kerros 2: Orkestrointi - silmukan hallinta ja reititys
# Kerros 3: Suoritus - työkalu- ja funktiokutsut
# Kerros 4: Havainnoitavuus - lokit, mittarit, jäljitykset
from openai import OpenAI
from dataclasses import dataclass, field
from datetime import datetime
import json
import time
import logging
logger = logging.getLogger("multi-outils")
@dataclass
class TraceExecution:
"""Suorituksen jäljitys valvontaa varten."""
requete_id: str
debut: float = field(default_factory=time.time)
tours: list = field(default_factory=list)
outils_utilises: list = field(default_factory=list)
tokens_total: int = 0
erreurs: list = field(default_factory=list)
duree_totale: float = 0.0
Tuotanto-orkestroija
class OrchestreurProduction:
def __init__(self, config: dict):
self.client = OpenAI()
self.config = config
self.tools = self._construire_tools(config)
self.dispatcher = self._construire_dispatcher(config)
def _construire_tools(self, config: dict) -> list:
"""Rakentaa työkalumatriisin konfiguraatiosta."""
tools = []
if config.get("file_search"):
tools.append({
"type": "file_search",
"vector_store_ids": config["file_search"]["vector_stores"],
"max_num_results": config["file_search"].get("max_results", 10)
})
if config.get("web_search"):
tools.append({
"type": "web_search",
"search_context_size": config["web_search"].get("context_size", "medium")
})
if config.get("code_interpreter"):
tools.append({"type": "code_interpreter", "container": {"type": "auto"}})
for func in config.get("fonctions", []):
tools.append(func)
return tools
def _construire_dispatcher(self, config: dict) -> dict:
"""Kartottaa funktioiden nimet niiden toteutuksiin."""
return config.get("implementations", {})
def executer(self, requete: str, fichiers: list = None,
max_tours: int = 10) -> dict:
"""Suorittaa pyynnön täydellisellä jäljityksellä."""
trace = TraceExecution(
requete_id=f"req_{int(time.time()*1000)}"
)
content = [{"type": "input_text", "text": requete}]
if fichiers:
for fid in fichiers:
content.append({"type": "input_file", "file_id": fid})
messages = [{"role": "user", "content": content}]
try:
for tour in range(max_tours):
debut_tour = time.time()
response = self.client.responses.create(
model=self.config.get("model", "gpt-5.6-terra"),
input=messages,
tools=self.tools,
instructions=self.config.get("instructions", "")
)
trace.tokens_total += response.usage.total_tokens
# Tunnista funktiokutsut
appels = [
item for item in response.output
if item.type == "function_call"
]
# Kirjaa käytetyt työkalut
for item in response.output:
if hasattr(item, "type"):
trace.outils_utilises.append(item.type)
trace.tours.append({
"numero": tour + 1,
"appels_fonction": len(appels),
"duree": time.time() - debut_tour
})
if not appels:
trace.duree_totale = time.time() - trace.debut
return {
"reponse": response.output_text,
"trace": trace
}
# Suorita mukautetut funktiot
resultats = self._executer_fonctions(appels, trace)
messages = response.output + resultats
except Exception as e:
trace.erreurs.append(str(e))
trace.duree_totale = time.time() - trace.debut
logger.error(f"Erreur requête {trace.requete_id}: {e}")
return {"reponse": None, "erreur": str(e), "trace": trace}
trace.duree_totale = time.time() - trace.debut
return {"reponse": "Limite de tours", "trace": trace}
def _executer_fonctions(self, appels: list, trace: TraceExecution) -> list:
"""Suorittaa funktiot virheenkäsittelyllä."""
resultats = []
for appel in appels:
try:
func = self.dispatcher.get(appel.name)
if not func:
raise ValueError(f"Fonction inconnue : {appel.name}")
args = json.loads(appel.arguments)
resultat = func(**args)
resultats.append({
"type": "function_call_output",
"call_id": appel.call_id,
"output": json.dumps(resultat)
})
except Exception as e:
trace.erreurs.append(f"{appel.name}: {str(e)}")
resultats.append({
"type": "function_call_output",
"call_id": appel.call_id,
"output": json.dumps({"error": str(e)})
})
return resultats
Deklaratiivinen konfiguraatio
Järjestelmämääritelmien siirtäminen koodista konfiguraatioon muuttaa sitä, kuka voi puuttua asioihin. Järjestelmäkehotteen säätäminen, työkalun poistaminen tai kustannuskaton muuttaminen muuttuu tiedostomuutokseksi – tarkistettavaksi ja peruutettavaksi – eikä enää käyttöönotoksi. Järjestelmässä, joka kehittyy viikoittain, tämä on ero iteroinnin ja reagoimisen välillä.
config_assistant_commercial = {
"model": "gpt-5.6-terra",
"instructions": (
"You are a sales assistant. You have access to CRM data, "
"product documentation, the web, and data analysis. "
"Prioritize internal data, enrich with web data."
),
"file_search": {
"vector_stores": ["vs_fiches_produit", "vs_propositions"],
"max_results": 10
},
"web_search": {
"context_size": "medium"
},
"code_interpreter": True,
"fonctions": [
{
"type": "function",
"name": "creer_opportunite",
"description": "Create an opportunity in the CRM",
"parameters": {
"type": "object",
"properties": {
"client": {"type": "string"},
"montant": {"type": "number"},
"probabilite": {"type": "integer"}
},
"required": ["client", "montant", "probabilite"],
"additionalProperties": False
},
"strict": True
}
],
"implementations": {
"creer_opportunite": lambda client, montant, probabilite:
crm_service.creer_opportunite(client, montant, probabilite)
}
}
orchestreur = OrchestreurProduction(config_assistant_commercial)
resultat = orchestreur.executer("Prepare a proposal for Acme Corp")
Havainnoitavuus ja valvonta
Mittaristo
Kolme mittaria riittää alkuun, ja kukin vastaa eri kysymykseen: viive työkalua kohden kertoo, mikä hidastaa järjestelmää, epäonnistumisaste työkalua kohden kertoo, mikä on hauras, ja kustannus pyyntöä kohden kertoo, mikä karkaa käsistä. Yleinen keskiarvo näistä kolmesta ei vastaa mihinkään näistä kysymyksistä.
class MetriquesMultiOutils:
def __init__(self):
self.requetes = []
def enregistrer(self, trace: TraceExecution):
self.requetes.append({
"id": trace.requete_id,
"timestamp": datetime.now().isoformat(),
"duree": trace.duree_totale,
"tours": len(trace.tours),
"tokens": trace.tokens_total,
"outils": list(set(trace.outils_utilises)),
"erreurs": len(trace.erreurs),
"cout_estime": self._estimer_cout(trace)
})
def _estimer_cout(self, trace: TraceExecution) -> float:
"""Arvioi suorituksen kustannuksen dollareina."""
# Arvioidut hinnat gpt-5.6-terralle: 2 $ / 12 $ miljoonaa kohden
cout_input = trace.tokens_total * 0.6 * 0.000002
cout_output = trace.tokens_total * 0.4 * 0.000012
return round(cout_input + cout_output, 4)
def rapport(self) -> dict:
if not self.requetes:
return {}
durees = [r["duree"] for r in self.requetes]
tokens = [r["tokens"] for r in self.requetes]
couts = [r["cout_estime"] for r in self.requetes]
return {
"total_requetes": len(self.requetes),
"duree_moyenne": sum(durees) / len(durees),
"tokens_moyen": sum(tokens) / len(tokens),
"cout_total": sum(couts),
"taux_erreur": sum(1 for r in self.requetes if r["erreurs"] > 0) / len(self.requetes),
"outils_les_plus_utilises": self._outils_frequents()
}
def _outils_frequents(self) -> dict:
compteur = {}
for r in self.requetes:
for outil in r["outils"]:
compteur[outil] = compteur.get(outil, 0) + 1
return dict(sorted(compteur.items(), key=lambda x: -x[1]))
Kustannusten hallinta
class GestionnaireCouts:
def __init__(self, budget_quotidien: float = 50.0):
self.budget = budget_quotidien
self.depenses_jour = 0.0
self.date_reset = datetime.now().date()
def peut_executer(self, cout_estime: float) -> bool:
"""Tarkistaa, salliiko budjetti suorituksen."""
aujourdhui = datetime.now().date()
if aujourdhui > self.date_reset:
self.depenses_jour = 0.0
self.date_reset = aujourdhui
return (self.depenses_jour + cout_estime) <= self.budget
def enregistrer_depense(self, cout: float):
self.depenses_jour += cout
def budget_restant(self) -> float:
return self.budget - self.depenses_jour
# Integrointi orkestroijaan
gestionnaire_couts = GestionnaireCouts(budget_quotidien=100.0)
def executer_avec_budget(orchestreur, requete, **kwargs):
cout_estime = 0.05 # Konservatiivinen arvio
if not gestionnaire_couts.peut_executer(cout_estime):
return {"erreur": "Daily budget reached", "restant": 0}
resultat = orchestreur.executer(requete, **kwargs)
cout_reel = resultat["trace"].tokens_total * 0.000002
gestionnaire_couts.enregistrer_depense(cout_reel)
return resultat
Malli: älykäs reititin
Käyttötapauksien lisääntyessä kiusaus on antaa kaikki yhdelle järjestelmälle, jossa on kaikki työkalut. Tämä on kallein valinta: jokainen pyyntö, jopa triviaalit, kantaa mukanaan koko työkalumääritelmien joukon. Reititin, joka luokittelee pyynnön ensin ja kutsuu sitten erikoistunutta orkestroijaa, pitää kontekstit lyhyinä ja tekee jokaisesta virrasta erikseen mitattavan.
class RouteurIntelligent:
def __init__(self):
self.client = OpenAI()
self.orchestreurs = {}
def enregistrer(self, domaine: str, orchestreur: OrchestreurProduction):
self.orchestreurs[domaine] = orchestreur
def router(self, requete: str) -> dict:
"""Määrittää toimialueen ja reitittää oikeaan orkestroijaan."""
# Nopea luokittelu kevyellä mallilla
response = self.client.responses.create(
model="gpt-5.6-terra",
input=f"Classify this request into a domain: {requete}\n"
f"Available domains: {list(self.orchestreurs.keys())}\n"
f"Respond only with the domain name.",
)
domaine = response.output_text.strip().lower()
if domaine not in self.orchestreurs:
domaine = "general" # Varasuunnitelma
logger.info(f"Requête routee vers : {domaine}")
return self.orchestreurs[domaine].executer(requete)
# Konfiguraatio
routeur = RouteurIntelligent()
routeur.enregistrer("commercial", OrchestreurProduction(config_assistant_commercial))
routeur.enregistrer("support", OrchestreurProduction(config_support))
routeur.enregistrer("rh", OrchestreurProduction(config_rh))
# Käyttö
resultat = routeur.router("How many vacation days do I have left?")
# -> Reitittää automaattisesti HR-orkestroijalle
Tuotantotarkistuslista
Tämä tarkistuslista on tarkoituksellisesti lyhyt. Se ei pyri täydellisyyteen, vaan kattaa kohdat, joiden puuttuminen maksaa sinulle häiriöinä eikä epämukavuutena – ja joita et ehdi lisätä kiireessä sinä päivänä, kun järjestelmä on jo käyttäjien käsissä.
checklist = {
"securite": [
"Validate arguments for each function",
"Rate limiting per user",
"Sanitize inputs and outputs",
"No sensitive data in logs"
],
"fiabilite": [
"Retry with backoff on transient errors",
"Circuit breaker per external service",
"Timeout per tool and per global request",
"Fallback when a tool is unavailable"
],
"performance": [
"Parallel execution of independent calls",
"Cache frequent search results",
"Limit the number of loop iterations",
"Choose the model adapted to complexity (gpt-5.6-terra vs gpt-5.6-terra)"
],
"observabilite": [
"Structured logging for each call",
"Latency and cost metrics",
"Alerts on error rate",
"Complete trace of each request"
],
"couts": [
"Daily budget with circuit breaker",
"Cost estimation before execution",
"Weekly spending report",
"Model choice optimization by complexity"
]
}
Keskeiset asiat
- Jaa kerroksiin: käyttöliittymä, orkestrointi, suoritus, havainnoitavuus
- Käytä deklaratiivista konfiguraatiota järjestelmien määrittelyyn
- Jäljitä jokainen suoritus valvontaa ja vianetsintää varten
- Toteuta kustannusten hallinta päivittäisellä budjetilla
- Älykäs reititin jakaa pyynnöt oikeille orkestroijille
Testaa tietämyksesi
Funktiokutsut, haku, suoritus: koko arsenaali viidessä kysymyksessä.
1. Mitä hyvän funktioskeeman tulisi sisältää?
Vastaus: Tiukat tyypit ja operatiiviset kuvaukset parametria kohden – tämä on sopimus, jota malli käyttää päättäessään, milloin kutsua ja miten täyttää; validointi hylkää loput.
2. Web Search vai File Search: miten valita?
Vastaus: Web Search julkiseen, tuoreeseen tietoon; File Search indeksoituihin dokumentteihisi (palastus + sisäänrakennettu sijoitus) – ja hybridi-haku yhdistää molemmat, kun vastaus ulottuu molempiin maailmoihin.
3. Mitä Code Interpreter mahdollistaa API:ssa?
Vastaus: Koodin suorittamisen hiekkalaatikossa: käsittele CSV/Excel/kuvia, laske tarkasti, tuota kaavioita – malli päättelee, koodi laskee, hiekkalaatikko eristää.
4. Mihin Tool Search tarvitaan?
Vastaus: Suuren työkaluluettelon dynaamiseen paljastamiseen: malli etsii relevantin työkalun sen sijaan, että se vastaanottaisi sata skeemaa kerralla – konteksti pysyy kevyenä, kyvyt valtavina.
5. Mitä sääntöjä sovelletaan usean työkalun arkkitehtuuriin tuotannossa?
Vastaus: Työkalut, joilla on selkeä scope, virheenkäsittely ja varasuunnitelmat työkalua kohden, rinnakkaiskutsut riippumattomille kutsuille ja havainnoitavuus jokaiselle kutsulle – robustius suunnitellaan työkalu kerrallaan.
Jokaisella työkalulla on oma maastonsa; tuotanto yhdistää ne – yllä oleva lopullinen arkkitehtuuri on viitesuunnitelmasi.