Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Arkkitehtuurit useilla työkaluilla tuotannossa

Oppitunti 20 / 20 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Arkkitehtuurit useilla työkaluilla tuotannossa
  2. Kerrosarkkitehtuuri
  3. Tuotanto-orkestroija
  4. Deklaratiivinen konfiguraatio
  5. Havainnoitavuus ja valvonta
  6. Kustannusten hallinta
  7. Malli: älykäs reititin
  8. Tuotantotarkistuslista
  9. Keskeiset asiat
  10. Testaa tietämyksesi

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 muodossa input_text, ja verkkohaku käyttää web_search-työkalua (web_search_preview on nyt vanhentunut työkalu ilman verkkotunnussuodattimia). Generoidut tiedostot haetaan käyttämällä oppitunnin 10 funktioita fichiers_generes ja telecharger. 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.