Architektury s více nástroji v produkci
Na této stránce
Aktualizováno 2. listopadu 2026 na základě dokumentace OpenAI: nástroj Code Interpreter nyní vyžaduje parametr
container(přidán do všech příkladů), části textového vstupu jsou typovány jakoinput_texta webové vyhledávání používá nástrojweb_search(web_search_previewje nyní zastaralý nástroj bez filtrů domén). Vygenerované soubory se získávají pomocí funkcífichiers_generesatelechargerz Lekce 10. Zdroje: Code Interpreter · Web search.
Architektury s více nástroji v produkci
Prototyp s více nástroji funguje proto, že jej používá jedna osoba, zná jeho limity a při selhání jej restartuje. Produkce odstraní všechny tři podmínky najednou. Kritické není kvalita odpovědi – ta už tam byla – ale tři vlastnosti, které prototypu chyběly: vědět, co se stalo při selhání volání, zabránit nekonečné smyčce, která vyčerpá rozpočet, a mít možnost upravit chování bez nového nasazení.
Následující vzory řeší každý jednu z těchto požadavků. Nepřijímej je všechny najednou: začni pozorovatelností, protože bez ní ani nezjistíš, které z ostatních ti chybí.
Vrstvená architektura
Oddělení odpovědností do vrstev není architektonická elegance: umožňuje nahradit každou část samostatně. Konkrétní přínos spočívá v tom, že můžeš změnit orchestraci, aniž bys se dotkl rozhraní, nebo přidat nástroj bez přepisování obchodní logiky. Čtyři níže uvedené vrstvy představují minimální rozdělení, které funguje v praxi.
# Vrstva 1: Rozhraní - příjem požadavků
# Vrstva 2: Orchestrace - správa smyček a směrování
# Vrstva 3: Exekuce - volání nástrojů a funkcí
# Vrstva 4: Pozorovatelnost - logy, metriky, stopy
from openai import OpenAI
from dataclasses import dataclass, field
from datetime import datetime
import json
import time
import logging
logger = logging.getLogger("multi-nastroje")
@dataclass
class StopaExekuce:
"""Stopa exekuce pro monitorování."""
id_pozadavku: str
zacatek: float = field(default_factory=time.time)
cykly: list = field(default_factory=list)
pouzite_nastroje: list = field(default_factory=list)
celkem_tokenu: int = 0
chyby: list = field(default_factory=list)
celkova_doba: float = 0.0
Produkční orchestrátor
class OrchestrujiciProdukce:
def __init__(self, konfigurace: dict):
self.klient = OpenAI()
self.konfigurace = konfigurace
self.nastroje = self._vytvorit_nastroje(konfigurace)
self.dispecer = self._vytvorit_dispecer(konfigurace)
def _vytvorit_nastroje(self, konfigurace: dict) -> list:
"""Vytvoří pole nástrojů z konfigurace."""
nastroje = []
if konfigurace.get("file_search"):
nastroje.append({
"type": "file_search",
"vector_store_ids": konfigurace["file_search"]["vector_stores"],
"max_num_results": konfigurace["file_search"].get("max_results", 10)
})
if konfigurace.get("web_search"):
nastroje.append({
"type": "web_search",
"search_context_size": konfigurace["web_search"].get("context_size", "medium")
})
if konfigurace.get("code_interpreter"):
nastroje.append({"type": "code_interpreter", "container": {"type": "auto"}})
for funkce in konfigurace.get("funkce", []):
nastroje.append(funkce)
return nastroje
def _vytvorit_dispecer(self, konfigurace: dict) -> dict:
"""Mapuje názvy funkcí na jejich implementace."""
return konfigurace.get("implementace", {})
def spustit(self, pozadavek: str, soubory: list = None,
max_cyklu: int = 10) -> dict:
"""Spustí požadavek s úplným sledováním."""
stopa = StopaExekuce(
id_pozadavku=f"req_{int(time.time()*1000)}"
)
obsah = [{"type": "input_text", "text": pozadavek}]
if soubory:
for id_souboru in soubory:
obsah.append({"type": "input_file", "file_id": id_souboru})
zpravy = [{"role": "user", "content": obsah}]
try:
for cyklus in range(max_cyklu):
zacatek_cyklu = time.time()
odpoved = self.klient.responses.create(
model=self.konfigurace.get("model", "gpt-5.6-terra"),
input=zpravy,
tools=self.nastroje,
instructions=self.konfigurace.get("instructions", "")
)
stopa.celkem_tokenu += odpoved.usage.total_tokens
# Identifikace volání funkcí
volani = [
polozka for polozka in odpoved.output
if polozka.type == "function_call"
]
# Záznam použitých nástrojů
for polozka in odpoved.output:
if hasattr(polozka, "type"):
stopa.pouzite_nastroje.append(polozka.type)
stopa.cykly.append({
"cislo": cyklus + 1,
"pocet_volani_funkci": len(volani),
"doba_trvani": time.time() - zacatek_cyklu
})
if not volani:
stopa.celkova_doba = time.time() - stopa.zacatek
return {
"odpoved": odpoved.output_text,
"stopa": stopa
}
# Spuštění vlastních funkcí
vysledky = self._spustit_funkce(volani, stopa)
zpravy = odpoved.output + vysledky
except Exception as e:
stopa.chyby.append(str(e))
stopa.celkova_doba = time.time() - stopa.zacatek
logger.error(f"Chyba požadavku {stopa.id_pozadavku}: {e}")
return {"odpoved": None, "chyba": str(e), "stopa": stopa}
stopa.celkova_doba = time.time() - stopa.zacatek
return {"odpoved": "Limit cyklů dosažen", "stopa": stopa}
def _spustit_funkce(self, volani: list, stopa: StopaExekuce) -> list:
"""Spustí funkce s ošetřením chyb."""
vysledky = []
for volani_polozka in volani:
try:
funkce = self.dispecer.get(volani_polozka.name)
if not funkce:
raise ValueError(f"Neznámá funkce: {volani_polozka.name}")
argumenty = json.loads(volani_polozka.arguments)
vysledek = funkce(**argumenty)
vysledky.append({
"type": "function_call_output",
"call_id": volani_polozka.call_id,
"output": json.dumps(vysledek)
})
except Exception as e:
stopa.chyby.append(f"{volani_polozka.name}: {str(e)}")
vysledky.append({
"type": "function_call_output",
"call_id": volani_polozka.call_id,
"output": json.dumps({"error": str(e)})
})
return vysledky
Deklarativní konfigurace
Přesun definic systému z kódu do konfigurace mění to, kdo může zasahovat. Úprava systémového promptu, odstranění nástroje nebo změna cenového stropu se stane změnou souboru – recenzovatelnou a vratnou – místo nasazení. U systému, který se vyvíjí každý týden, je to rozdíl mezi iterací a reakcí.
konfigurace_obchodni_asistent = {
"model": "gpt-5.6-terra",
"instructions": (
"Jsi obchodní asistent. Máš přístup k datům CRM, "
"produktové dokumentaci, webu a analýze dat. "
"Upřednostňuj interní data, obohacuj je daty z webu."
),
"file_search": {
"vector_stores": ["vs_listy_produktu", "vs_nabidky"],
"max_results": 10
},
"web_search": {
"context_size": "medium"
},
"code_interpreter": True,
"funkce": [
{
"type": "function",
"name": "vytvorit_prilezitost",
"description": "Vytvořit příležitost v CRM",
"parameters": {
"type": "object",
"properties": {
"klient": {"type": "string"},
"castka": {"type": "number"},
"pravdepodobnost": {"type": "integer"}
},
"required": ["klient", "castka", "pravdepodobnost"],
"additionalProperties": False
},
"strict": True
}
],
"implementace": {
"vytvorit_prilezitost": lambda klient, castka, pravdepodobnost:
crm_sluzba.vytvorit_prilezitost(klient, castka, pravdepodobnost)
}
}
orchestrator = OrchestrujiciProdukce(konfigurace_obchodni_asistent)
vysledek = orchestrator.spustit("Připrav nabídku pro společnost Acme Corp")
Pozorovatelnost a monitorování
Dashboard metrik
Ke startu stačí tři metriky a každá odpovídá na jinou otázku: latence na nástroj ti řekne, který systém zpomaluje, míra selhání na nástroj ukáže, který je křehký, a náklady na požadavek odhalí, který se vymyká kontrole. Globální průměr ze všech tří neodpoví na žádnou z těchto otázek.
class MetrikyViceNastroju:
def __init__(self):
self.pozadavky = []
def zaznamenat(self, stopa: StopaExekuce):
self.pozadavky.append({
"id": stopa.id_pozadavku,
"casove_razitko": datetime.now().isoformat(),
"doba_trvani": stopa.celkova_doba,
"pocet_cyklu": len(stopa.cykly),
"tokeny": stopa.celkem_tokenu,
"nastroje": list(set(stopa.pouzite_nastroje)),
"pocet_chyb": len(stopa.chyby),
"odhad_nakladu": self._odhadnout_naklady(stopa)
})
def _odhadnout_naklady(self, stopa: StopaExekuce) -> float:
"""Odhadne náklady v dolarech za exekuci."""
# Přibližné sazby pro gpt-5.6-terra: 2 $ / 12 $ za milion
naklad_vstup = stopa.celkem_tokenu * 0.6 * 0.000002
naklad_vystup = stopa.celkem_tokenu * 0.4 * 0.000012
return round(naklad_vstup + naklad_vystup, 4)
def zprava(self) -> dict:
if not self.pozadavky:
return {}
doby = [r["doba_trvani"] for r in self.pozadavky]
tokeny = [r["tokeny"] for r in self.pozadavky]
naklady = [r["odhad_nakladu"] for r in self.pozadavky]
return {
"celkem_pozadavku": len(self.pozadavky),
"prumerna_doba": sum(doby) / len(doby),
"prumerny_pocet_tokenu": sum(tokeny) / len(tokeny),
"celkove_naklady": sum(naklady),
"mira_chybovosti": sum(1 for r in self.pozadavky if r["pocet_chyb"] > 0) / len(self.pozadavky),
"nejpouzivanejsi_nastroje": self._casto_pouzivane_nastroje()
}
def _casto_pouzivane_nastroje(self) -> dict:
pocitadlo = {}
for r in self.pozadavky:
for nastroj in r["nastroje"]:
pocitadlo[nastroj] = pocitadlo.get(nastroj, 0) + 1
return dict(sorted(pocitadlo.items(), key=lambda x: -x[1]))
Správa nákladů
class SpravceNakladu:
def __init__(self, denni_rozpocet: float = 50.0):
self.rozpocet = denni_rozpocet
"denni_utrata": 0.0
self.datum_resetu = datetime.now().date()
def muze_spustit(self, odhad_nakladu: float) -> bool:
"""Zkontroluje, zda rozpočet umožňuje spuštění."""
dnes = datetime.now().date()
if dnes > self.datum_resetu:
self.denni_utrata = 0.0
self.datum_resetu = dnes
return (self.denni_utrata + odhad_nakladu) <= self.rozpocet
def zaznamenat_utratu(self, naklad: float):
self.denni_utrata += naklad
def zbyvajici_rozpocet(self) -> float:
return self.rozpocet - self.denni_utrata
# Integrace do orchestrátoru
spravce_nakladu = SpravceNakladu(denni_rozpocet=100.0)
def spustit_s_rozpoctem(orchestrator, pozadavek, **kwargs):
odhad_nakladu = 0.05 # Konzervativní odhad
if not spravce_nakladu.muze_spustit(odhad_nakladu):
return {"chyba": "Denní rozpočet vyčerpán", "zbytek": 0}
vysledek = orchestrator.spustit(pozadavek, **kwargs)
skutecny_naklad = vysledek["stopa"].celkem_tokenu * 0.000002
spravce_nakladu.zaznamenat_utratu(skutecny_naklad)
return vysledek
Vzor: inteligentní směrovač
S přibývajícími případy použití vzniká pokušení předat vše jednomu systému vybavenému všemi nástroji. To je nejdražší volba: každý požadavek, i ten triviální, nese celou sadu definic nástrojů. Směrovač, který nejprve klasifikuje požadavek a poté zavolá specializovaný orchestrátor, udržuje kontexty krátké a umožňuje měřit každý tok samostatně.
class InteligentniSmerovac:
def __init__(self):
self.klient = OpenAI()
self.orchestratory = {}
def registrovat(self, domena: str, orchestrator: OrchestrujiciProdukce):
self.orchestratory[domena] = orchestrator
def smerovat(self, pozadavek: str) -> dict:
"""Určí doménu a směruje ke správnému orchestrátoru."""
# Rychlá klasifikace pomocí lehkého modelu
odpoved = self.klient.responses.create(
model="gpt-5.6-terra",
input=f"Klasifikuj tento požadavek do domény: {pozadavek}\n"
f"Dostupné domény: {list(self.orchestratory.keys())}\n"
f"Odpověz pouze názvem domény.",
)
domena = odpoved.output_text.strip().lower()
if domena not in self.orchestratory:
domena = "obecne" # Záložní možnost
logger.info(f"Požadavek směrován do: {domena}")
return self.orchestratory[domena].spustit(pozadavek)
# Konfigurace
smerovac = InteligentniSmerovac()
smerovac.registrovat("obchod", OrchestrujiciProdukce(konfigurace_obchodni_asistent))
smerovac.registrovat("podpora", OrchestrujiciProdukce(konfigurace_podpora))
smerovac.registrovat("lidske_zdroje", OrchestrujiciProdukce(konfigurace_lz))
# Použití
vysledek = smerovac.smerovat("Kolik mi zbývá dnů dovolené?")
# -> Automaticky směruje k orchestrátoru lidských zdrojů
Kontrolní seznam pro produkci
Tento kontrolní seznam je úmyslně krátký. Nesnaží se o vyčerpávající výčet, ale pokrývá body, jejichž absence tě stojí incidenty, nikoliv jen nepohodlí – a které nemůžeš přidat ve spěchu v den, kdy je systém již v rukou uživatelů.
kontrolni_seznam = {
"bezpecnost": [
"Validovat argumenty pro každou funkci",
"Omezení rychlosti na uživatele",
"Čištění vstupů a výstupů",
"Žádná citlivá data v logách"
],
"spolehlivost": [
"Opakování s exponenciálním čekáním při přechodných chybách",
"Jistič pro každou externí službu",
"Časový limit pro každý nástroj a pro celý požadavek",
"Záložní řešení při nedostupnosti nástroje"
],
"vykon": [
"Paralelní exekuce nezávislých volání",
"Mezipaměť pro časté výsledky vyhledávání",
"Omezení počtu iterací smyčky",
"Volba modelu přizpůsobená složitosti (gpt-5.6-terra vs gpt-5.6-terra)"
],
"pozorovatelnost": [
"Strukturované logování pro každé volání",
"Metriky latence a nákladů",
"Upozornění na míru chyb",
"Úplná stopa každého požadavku"
],
"naklady": [
"Denní rozpočet s jističem",
"Odhad nákladů před spuštěním",
"Týdenní zpráva o výdajích",
"Optimalizace výběru modelu podle složitosti"
]
}
Klíčové poznatky
- Rozdělení do vrstev: rozhraní, orchestrace, exekuce, pozorovatelnost
- Použití deklarativní konfigurace pro definici systémů
- Sledování každé exekuce pro monitorování a ladění
- Implementace správce nákladů s denním rozpočtem
- Inteligentní směrovač distribuuje požadavky ke správným orchestrátorům
Ověř si své znalosti
Volání funkcí, vyhledávání, exekuce: celý arzenál v pěti otázkách.
1. Co by měl obsahovat dobrý schéma funkce?
Odpověď: Přísné typy a operativní popisy pro každý parametr – to je smlouva, kterou model používá k rozhodnutí, kdy volat a jak vyplnit; validace ostatní odmítne.
2. Webové vyhledávání nebo vyhledávání v souborech: jak vybrat?
Odpověď: Webové vyhledávání pro veřejné, nedávné informace; vyhledávání v souborech pro tvé indexované dokumenty (chunking + vestavěné řazení) – a hybridní vyhledávání kombinuje obojí, když odpověď zasahuje oba světy.
3. Co umožňuje Code Interpreter v API?
Odpověď: Spouštět kód v sandboxu: zpracovávat CSV/Excel/obrázky, přesně počítat, vytvářet grafy – model usuzuje, kód počítá, sandbox izoluje.
4. K čemu slouží Tool Search?
Odpověď: K dynamickému vystavení velkého katalogu nástrojů: model hledá relevantní nástroj místo toho, aby dostal najednou sto schémat – kontext zůstává lehký, schopnosti zůstávají rozsáhlé.
5. Jaká pravidla platí pro architekturu s více nástroji v produkci?
Odpověď: Nástroje s jasným rozsahem, ošetření chyb a záložní řešení pro každý nástroj, paralelní volání při nezávislosti a pozorovatelnost pro každé volání – robustnost se navrhuje nástroj po nástroji.
Každý nástroj má své teritorium; produkce je kombinuje – výše uvedená finální architektura je tvým referenčním plánem.