Arhitecturi multi-instrument în producție
Pe această pagină
Actualizat la 2 noiembrie 2026 pe baza documentației OpenAI: instrumentul Code Interpreter necesită acum un parametru
container(adăugat la toate exemplele), părțile de intrare text sunt tipate cainput_text, iar căutarea web folosește instrumentulweb_search(web_search_previeweste acum un instrument legacy fără filtre de domeniu). Fișierele generate sunt recuperate folosind funcțiilefichiers_generesșitelechargerdin Lecția 10. Surse: Code Interpreter · Web search.
Arhitecturi multi-instrument în producție
Un prototip multi-instrument funcționează deoarece o singură persoană îl utilizează, îi cunoaște limitele și îl repornește când eșuează. Producția elimină simultan toate cele trei condiții. Ceea ce devine critic nu este calitatea răspunsului — aceasta exista deja — ci trei proprietăți pe care prototipul nu le avea: să știți ce s-a întâmplat când o apelare eșuează, să preveniți ca o buclă necontrolată să vă epuizeze bugetul și să puteți modifica comportamentul fără a reimplanta aplicația.
Modelele de mai jos abordează fiecare câte una dintre aceste cerințe. Nu le adoptați pe toate deodată: începeți cu observabilitatea, deoarece fără ea nici nu veți ști care dintre celelalte vă lipsește.
Arhitectură stratificată
Separarea responsabilităților în straturi nu este o eleganță arhitecturală: face ca fiecare parte să fie înlocuibilă. Beneficiul concret este că puteți schimba orchestrarea fără a atinge interfața sau puteți adăuga un instrument fără a rescrie logica de afaceri. Cele patru straturi de mai jos reprezintă defalcarea minimă care rezistă în practică.
# Stratul 1: Interfață - recepția cererilor
# Stratul 2: Orchestrare - gestionarea buclelor și rutarea
# Stratul 3: Execuție - apeluri de instrumente și funcții
# Stratul 4: Observabilitate - jurnale, metrici, urme
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:
"""Urmă de execuție pentru monitorizare."""
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
Orchestrator de producție
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:
"""Construiește tabloul de instrumente din configurație."""
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:
"""Mapează numele funcțiilor la implementările lor."""
return config.get("implementations", {})
def executer(self, requete: str, fichiers: list = None,
max_tours: int = 10) -> dict:
"""Execută o cerere cu urmărire completă."""
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
# Identifică apelurile de funcții
appels = [
item for item in response.output
if item.type == "function_call"
]
# Înregistrează instrumentele utilizate
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
}
# Execută funcțiile personalizate
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:
"""Execută funcțiile cu gestionarea erorilor."""
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
Configurație declarativă
Mutarea definițiilor sistemului din cod în configurație schimbă cine poate interveni. Ajustarea unui prompt de sistem, eliminarea unui instrument sau modificarea unui plafon de cost devine o modificare de fișier — revizuibilă și reversibilă — în loc de o implantare. Pe un sistem care evoluează săptămânal, aceasta este diferența dintre iterare și reacție.
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")
Observabilitate și monitorizare
Panou de metrici
Trei metrici sunt suficiente pentru început, iar fiecare răspunde la o întrebare diferită: latența per instrument vă spune care dintre ele încetinește sistemul, rata de eșec per instrument vă spune care este fragil, iar costul per cerere vă spune care devine excesiv. O medie globală pentru toate cele trei nu răspunde la niciuna dintre aceste întrebări.
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:
"""Estimează costul în dolari al execuției."""
# Rate aproximative pentru gpt-5.6-terra: 2 $ / 12 $ per milion
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]))
Gestionarea costurilor
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:
"""Verifică dacă bugetul permite execuția."""
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
# Integrare în orchestrator
gestionnaire_couts = GestionnaireCouts(budget_quotidien=100.0)
def executer_avec_budget(orchestreur, requete, **kwargs):
cout_estime = 0.05 # Estimare conservatoare
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
Model: router inteligent
Pe măsură ce cazurile de utilizare se înmulțesc, tentația este de a încredința totul unui singur sistem echipat cu fiecare instrument. Aceasta este cea mai costisitoare alegere: fiecare cerere, chiar și cele banale, poartă setul complet de definiții de instrumente. Un router care clasifică mai întâi cererea, apoi apelează un orchestrator specializat, menține contextele scurte și face ca fiecare flux să fie măsurabil separat.
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:
"""Determină domeniul și rutează către orchestratorul corect."""
# Clasificare rapidă cu un model ușor
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" # Fallback
logger.info(f"Requête routee vers : {domaine}")
return self.orchestreurs[domaine].executer(requete)
# Configurație
routeur = RouteurIntelligent()
routeur.enregistrer("commercial", OrchestreurProduction(config_assistant_commercial))
routeur.enregistrer("support", OrchestreurProduction(config_support))
routeur.enregistrer("rh", OrchestreurProduction(config_rh))
# Utilizare
resultat = routeur.router("How many vacation days do I have left?")
# -> Rutează automat către orchestratorul HR
Listă de verificare pentru producție
Această listă de verificare este intenționat scurtă. Nu își propune exhaustivitatea, ci acoperă punctele a căror absență vă costă în incidente, nu doar în disconfort — și pe care nu le puteți adăuga în grabă în ziua în care sistemul este deja în mâinile utilizatorilor.
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"
]
}
Puncte cheie
- Descompuneți în straturi: interfață, orchestrare, execuție, observabilitate
- Utilizați configurația declarativă pentru a defini sistemele
- Urmăriți fiecare execuție pentru monitorizare și depanare
- Implementați un manager de costuri cu buget zilnic
- Un router inteligent distribuie cererile către orchestratoarele potrivite
Testați-vă cunoștințele
Apelarea funcțiilor, căutarea, execuția: întregul arsenal în cinci întrebări.
1. Ce ar trebui să conțină o schemă de funcție bună?
Răspuns: Tipuri stricte și descrieri operaționale per parametru — acesta este contractul pe care modelul îl folosește pentru a decide când să apeleze și cum să completeze; validarea respinge restul.
2. Web Search sau File Search: cum alegi?
Răspuns: Web Search pentru informații publice și recente; File Search pentru documentele indexate (chunking + clasificare integrată) — iar căutarea hibridă le combină pe ambele când răspunsul se întinde peste ambele lumi.
3. Ce permite Code Interpreter în API?
Răspuns: Executarea codului într-un sandbox: procesarea fișierelor CSV/Excel/imagine, calcul precis, generarea de grafice — modelul raționează, codul calculează, sandbox-ul izolează.
4. La ce servește Tool Search?
Răspuns: Pentru a expune dinamic un catalog mare de instrumente: modelul caută instrumentul relevant în loc să primească o sută de scheme deodată — contextul rămâne ușor, capabilitățile rămân vaste.
5. Ce reguli se aplică unei arhitecturi multi-instrument în producție?
Răspuns: Instrumente cu scop clar, gestionarea erorilor și fallback-uri per instrument, apeluri paralele când sunt independente și observabilitate pentru fiecare apel — robustețea este proiectată instrument cu instrument.
Fiecare instrument are terenul său; producția le combină — arhitectura finală de mai sus este planul dumneavoastră de referință.