Salt la conținutul principal
Română— Alege o limbă
Meniu

Arhitecturi multi-instrument în producție

Lecția 20 din 20 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Arhitecturi multi-instrument în producție
  2. Arhitectură stratificată
  3. Orchestrator de producție
  4. Configurație declarativă
  5. Observabilitate și monitorizare
  6. Gestionarea costurilor
  7. Model: router inteligent
  8. Listă de verificare pentru producție
  9. Puncte cheie
  10. Testați-vă cunoștințele

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 ca input_text, iar căutarea web folosește instrumentul web_search (web_search_preview este acum un instrument legacy fără filtre de domeniu). Fișierele generate sunt recuperate folosind funcțiile fichiers_generes și telecharger din 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ță.