Arhitekture z več orodji v proizvodnji
Na tej strani
Posodobljeno 2. novembra 2026 na podlagi dokumentacije OpenAI: orodje Code Interpreter zdaj zahteva parameter
container(dodan vsem primerom), vhodni deli besedila so tipizirani kotinput_text, spletno iskanje pa uporablja orodjeweb_search(web_search_previewje zdaj zastarelo orodje brez filtrov domen). Ustvarjene datoteke se pridobijo s funkcijamafichiers_generesintelechargeriz lekcije 10. Viri: Code Interpreter · Web search.
Arhitekture z več orodji v proizvodnji
Prototip z več orodji deluje, ker ga uporablja ena sama oseba, pozna njegove omejitve in ga ob napaki ponovno zažene. Proizvodnja hkrati odpravi vse tri pogoje. Kritično ne postane kakovost odgovora – ta je bila že prisotna – temveč tri lastnosti, ki jih prototipu manjkajo: vedeti, kaj se je zgodilo, ko klic odpove, preprečiti, da bi zanka v neskončnost izpraznila vaš proračun, in možnost spreminjanja vedenja brez ponovne uvedbe.
Spodnji vzorci naslavljajo vsak po eno od teh zahtev. Ne sprejmite jih vseh naenkrat: začnite z opazljivostjo, saj brez nje sploh ne boste vedeli, katere od drugih vam manjkajo.
Slojevita arhitektura
Ločevanje odgovornosti v sloje ni arhitekturna eleganca: omogoča zamenljivost vsakega dela. Konkretna korist je, da lahko spremenite orkestracijo, ne da bi se dotaknili vmesnika, ali dodate orodje brez prepisovanja poslovne logike. Štirje spodnji sloji so minimalna razčlenitev, ki se obnese v praksi.
# Sloj 1: Vmesnik - sprejem zahtevkov
# Sloj 2: Orkestracija - upravljanje zank in usmerjanje
# Sloj 3: Izvajanje - klici orodij in funkcij
# Sloj 4: Opazljivost - dnevniki, metrike, sledi
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:
"""Sled izvajanja za nadzor."""
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
Proizvodni orkestrator
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:
"""Zgradi polje orodij iz konfiguracije."""
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:
"""Preslika imena funkcij v njihove implementacije."""
return config.get("implementations", {})
def executer(self, requete: str, fichiers: list = None,
max_tours: int = 10) -> dict:
"""Izvede zahtevek s popolnim sledenjem."""
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
# Identificiraj klice funkcij
appels = [
item for item in response.output
if item.type == "function_call"
]
# Zabeleži uporabljena orodja
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
}
# Izvedi funkcije po meri
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:
"""Izvede funkcije z obravnavo napak."""
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
Deklarativna konfiguracija
Prenos definicij sistema iz kode v konfiguracijo spremeni tiste, ki lahko posežejo v sistem. Prilagoditev sistemskega poziva, odstranitev orodja ali sprememba stroškovne omejitve postane sprememba datoteke – pregledna in razveljavljiva – namesto uvedbe. Pri sistemu, ki se razvija tedensko, je to razlika med iteriranjem in reagiranjem.
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")
Opazljivost in nadzor
Nadzorna plošča metrik
Za začetek zadostujejo tri metrike, vsaka pa odgovarja na drugačno vprašanje: zakasnitev na orodje vam pove, katero upočasnjuje sistem, stopnja napak na orodje vam pove, katero je krhko, strošek na zahtevek pa vam pove, katero uhaja iz nadzora. Globalno povprečje vseh treh ne odgovori na nobeno od teh vprašanj.
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:
"""Ocenjuje strošek izvajanja v dolarjih."""
# Priblične stopnje za gpt-5.6-terra: 2 $ / 12 $ na milijon
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]))
Upravljanje stroškov
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:
"""Preveri, ali proračun dopušča izvajanje."""
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
# Integracija v orkestrator
gestionnaire_couts = GestionnaireCouts(budget_quotidien=100.0)
def executer_avec_budget(orchestreur, requete, **kwargs):
cout_estime = 0.05 # Konzervativna ocena
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
Vzorec: inteligentni usmerjevalnik
Ko se primeri uporabe množijo, je skušnava vse prepustiti enemu samemu sistemu, opremljenemu z vsemi orodji. To je najdražja izbira: vsak zahtevek, celo trivialni, nosi celoten nabor definicij orodij. Usmerjevalnik, ki najprej razvrsti zahtevek, nato pa pokliče specializiranega orkestratorja, ohranja kontekste kratke in omogoča ločeno merjenje vsakega toka.
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:
"""Določi domeno in usmeri k pravemu orkestratorju."""
# Hitra razvrstitev z lahkotnim modelom
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" # Nadomestna možnost
logger.info(f"Requête routee vers : {domaine}")
return self.orchestreurs[domaine].executer(requete)
# Konfiguracija
routeur = RouteurIntelligent()
routeur.enregistrer("commercial", OrchestreurProduction(config_assistant_commercial))
routeur.enregistrer("support", OrchestreurProduction(config_support))
routeur.enregistrer("rh", OrchestreurProduction(config_rh))
# Uporaba
resultat = routeur.router("How many vacation days do I have left?")
# -> Samodejno usmeri k orkestratorju za kadre
Kontrolni seznam za proizvodnjo
Ta kontrolni seznam je namerno kratek. Ne cilja na izčrpnost, temveč pokriva točke, katerih odsotnost vas stane v incidentih, ne le v nelagodju – in ki jih ne morete dodati v naglici na dan, ko je sistem že v rokah uporabnikov.
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"
]
}
Ključne ugotovitve
- Razčlenite na sloje: vmesnik, orkestracija, izvajanje, opazljivost
- Uporabite deklarativno konfiguracijo za definiranje sistemov
- Sledite vsakemu izvajanju zaradi nadzora in odpravljanja napak
- Implementirajte upravitelja stroškov z dnevnim proračunom
- Inteligentni usmerjevalnik porazdeli zahtevke k pravim orkestratorjem
Preveri svoje znanje
Klicanje funkcij, iskanje, izvajanje: celoten arzenal v petih vprašanjih.
1. Kaj mora vsebovati dobra shema funkcije?
Odgovor: Stroge tipe in operativne opise za vsak parameter – to je pogodba, ki jo model uporabi za odločitev, kdaj poklicati in kako izpolniti; preverjanje zavrne vse ostalo.
2. Spletno iskanje ali iskanje po datotekah: kako izbrati?
Odgovor: Spletno iskanje za javne, nedavne informacije; iskanje po datotekah za vaše indeksirane dokumente (razčlenjevanje + vgrajeno razvrščanje) – hibridno iskanje pa združi oboje, ko odgovor zajema oba svetova.
3. Kaj omogoča Code Interpreter v API-ju?
Odgovor: Izvajanje kode v peskovniku: obdelava CSV/Excel/slik, natančni izračuni, ustvarjanje grafikonov – model razmišlja, koda računa, peskovnik izolira.
4. Čemu služi Tool Search?
Odgovor: Dinamični izpostavitvi velikega kataloga orodij: model išče ustrezno orodje, namesto da bi naenkrat prejel sto shem – kontekst ostaja lahek, zmogljivosti ostajajo obsežne.
5. Katera pravila veljajo za arhitekturo z več orodji v proizvodnji?
Odgovor: Orodja z jasnim obsegom, obravnava napak in nadomestne možnosti za vsako orodje, vzporedni klici, ko so neodvisni, in opazljivost za vsak klic – robustnost je zasnovana orodje za orodjem.
Vsako orodje ima svoj teren; proizvodnja jih združuje – zgornja končna arhitektura je vaš referenčni načrt.