Галоўная / Артыкулы

Больш чым абгортка над API: пасярэдніцкі ўзровень для прадакшн-інтэграцыі LLM

Прамыя выклікі LLM API ламаюцца пад рэальным трафікам. Пасярэдніцкі ўзровень дадае абстракцыю мадэляў, рэзервовую маршрутызацыю, падзейных агентаў і выбар мадэлі з улікам кошту.

Выдавец: REACTAPP.TOP6 хв чытання1347 слоў

Крыніцы: Pragmatic AI Integration: Moving beyond the API wrapper

Большынства команд дадзеяе AI да продукту самым быстрым спосабам: гэта проста абгортка навакол API прадаўцы, пры чым LLM адносіцца як і любая іншая зовнішня служба. Гэта здаецца разумным, але на практыцы гэта не працуе. Абгортка стае кранглівай залежнасцю і не можа падтрымаць бэкенд, які можа масштабавацца.

Разглядзім кансоль для чату, якая не мае з’язку з базамі дадзеных пасобнікаў і не выкарыстоўвае ролі IAM для выканання дзеянняў. Гэта можа зачараваць у дэманстрацыі, але гэта знаходзіцца параду з важлівымі рабочымі працэсамі, таму AI застаецца толькі новынкай. Такая наладка неправаляўна адначыта, куды пераходзіць складнасць. Сучасныя бэкенды AI пераносяць іх з UI ў інфраструктуру. Настоямая задача — не вызыванне API, а праектаванне архітэктуры AI, якая можа выжыць пасля абыякіх збоёў.

Разлік між базовай і стойкай інтэграцыяй мае прымытныя практычныя наследкі, таму яна лячыцца аднай з галоўных рашэнняў, касаючыхся гатовасці да працы.

Дзе збываюцца кэшэры

Прымытныя кэшэры API рэгулярна сталкаюцца з складнымі крайнімі кейсамі пад час працы. Команды таксама недаўаюць значэння практычным мерыям, такім як ліміты частоты, квоты токенаў і фільтрацыя введанняў.

Тыповы прыклад неудачы: агент для е-камерцыі продаваў продукты, неправямо обрабоўваючы запыты на вярнуць тавары, таму што дакументацыя API для доставкі перыяднавала певныя поля. Мадэль чытала гэтыя поля буквальна і неправямо запалняла параметры функцыі. LLM-ы дзівным чынам бяруць все буквальна, таму неясная або застарэлая дакументацыя API і вызначэнні функцый прыводзяць да неправямых або неудачных вызоў.

Прычына не ў слабай моцы модэлю. Гэта шумны выхід API і дробныя дэталі документацыі, якія прыяўляюцца толькі у масштабных сценарыях. У базовай інтэграцыі няма альтэрнатыўы, таму якосьць службы розыходзіцца рошчэдза, калі ўтвараюцца проблемы.

Ось як выглядае нестабільная версія — прымітны вызов для завершэння чату без мінімальнага керавання памілкамі:

import openai
# Replace with your actual API key or ensure it's set in an
environment variable
# openai.api_key = "YOUR_API_KEY"
model_name = "gpt-5.2" # Hardcoded model name
user_prompt = "Tell me a short, interesting fact about space."
# Simple string prompt
try:
 # Make a direct call to the Chat Completions API
 client = OpenAI(api_key="YOUR_API_KEY")
response = openai.ChatCompletion.create(
 model=model_name,
 messages=[
 {"role": "user", "content": user_prompt}
 ]
 )
 # Print the assistant's reply
 print(response.choices[0].message.content)
except openai.OpenAIError as e:
 # Catch specific OpenAI API errors
 print(f"An OpenAI API error occurred: {e}")
except Exception as e:
 # Catch any other unexpected errors
 print(f"An unexpected error occurred: {e}")

Спецыяльны слой інтэграцыі

Адказам ёст мідлвэр-слой між прыкладным праграмам і прадаўцамі модэляў. Ён маскіруе спецыфіку прадаўцоў, таму сістэма можа пераходзіць, напрыклад, з OpenAI на Anthropic, не перапісваючы основную логіку прыкладнага праграмы. Слой таксама павінен стандартызаваць схемы вхідных і выхідных дадзеных, каб код прыкладнага праграмы вярбаваўся праз аднаковы інтэрфейс, незалежна ад таго, які модэль знаходзіцца за ям.

Сюды таксама належаць іншыя абавязкі: версіяванне запытоў, можлівасць назірання за крытычнымі параметрамі і альтэрнатывны маршрутызацыя для паставання працысу. Калі дорогі основны модэль не вярнуеся за пазначаны час, слой можа праказаць запыт на болей шырокі, дышчыцый модэль, тады корыстувачы не будуць чакаць, а вітраты застануцца пад контролем.

Агенты, керованы запускамі, заместо вікнаў чату

Калі такая база будзе створана, сістэма можа перайсці з сінхроннага чату да асінхронных фонавых агентаў, якія запускаюцца пад час выканання задач у прыкладнай програме. У працы такога агента няма патрэбы чакаць, пакуль хтось запішае запіт — ён дзеяе сама, калі ўтвараецца паводак. Webhooks у поўнай злучэнні з вызывамі функцый автаматычна запускаюць робочыя працэсы, кераваныя ШЫ. Паколькі логіка ШЫ больш не знаходзіцца на галоўнай ніткі прыкладнай програмы, сістэма застаецца рэагіруючай.

Хорашым прыкладам ёсць новы крытычны тыкет на падтрымку. Сама стварэнне тыкета ёсць паводком, і webhook прызывае агента, які чытае тыкет, падсумавляе яго, шукае актуальныя внутранія дакументы і прадае праект адпаведзення, які можа пераглянуць чалавек.

Логіку такога агента можна запісаць так:

import json
from typing import Dict, Any
def handle_new_ticket_webhook(event_payload: Dict[str, Any]) -> Dict[str, Any]:
 """
 Handles a 'new_ticket' webhook event by constructing a prompt and
 calling an LLM orchestrator.
 """
 event_type = event_payload.get("event_type")
 ticket_data = event_payload.get("data", {})
 if event_type != "new_ticket":
 # Ignore events that are not 'new_ticket'
 return {"status": "ignored", "message": "Not a new_ticket event"}
 ticket_id = ticket_data.get("ticket_id")
 subject = ticket_data.get("subject")
 description = ticket_data.get("description")
 requester_email = ticket_data.get("requester_email")
 if not all([ticket_id, subject, description, requester_email]):
 # Validate essential ticket data
 return {"status": "error", "message": "Missing essential ticket data"}
 # Construct a comprehensive prompt for the LLM based on the new ticket
 prompt = (
 f"A new support ticket (ID: {ticket_id}) has been created.
"
 f"Subject: {subject}
"
 f"Description: {description}
"
 f"Requester: {requester_email}
"
 "Please analyze this ticket. Use internal documentation to find relevant "
 "solutions or escalation paths, and if necessary, use communication tools "
 "to gather more information or update the requester."
 )
 try:
 # Call the orchestrator with the generated prompt
 # The orchestrator is expected to use an LLM with function-calling capabilities
 # to interact with various internal APIs (e.g., documentation search, email, chat).
 orchestrator_response = call_llm_orchestrator(prompt, ticket_id)
 return {"status": "success", "ticket_id": ticket_id, "orchestrator_output": orchestrator_response}
 except Exception as e:
 # Handle potential errors during the orchestrator call
 return {"status": "error", "ticket_id": ticket_id, "message": f"Orchestrator call failed: {e}"}
def call_llm_orchestrator(prompt: str, ticket_id: str) -> Dict[str, Any]:
 """
 Placeholder for the function that calls the LLM orchestrator.
 In a real scenario, this would interact with an LLM service.
 """
 # Simulate an orchestrator response
 # This might include actions taken, suggested next steps, or a summary.
 print(f"Calling LLM Orchestrator for Ticket ID: {ticket_id} with prompt:
{prompt[:100]}…")

 # Example of a function-calling interaction: LLM might decide to search docs
 # or draft an email.

 # Placeholder for actual LLM interaction and function calling logic
 # orchestrator_llm.invoke(prompt, tools=[search_docs, send_email, update_ticket_status])

 return {
 "action_suggested": "initial assessment complete",
 "next_steps": ["search internal knowledge base", "draft initial response"],
 "orchestrator_version": "v1.0"
 }
# Example usage (simulating a Flask/FastAPI request body)
if __name__ == "__main__":
 example_payload = {
 "event_type": "new_ticket",
 "data": {
 "ticket_id": "TKT-2023–001",
 "subject": "Email delivery issues for user X",
 "description": "User X reports not receiving emails since yesterday morning. Checked spam, nothing there.",
 "requester_email": "user.x@example.com",
 "priority": "high",
 "category": "Email Service"
 },
 "timestamp": "2023–10–27T10:00:00Z"
 }
 response = handle_new_ticket_webhook(example_payload)
 print("
Webhook Handler Response:")
 print(json.dumps(response, indent=2))
 # Example of a non-new_ticket event
 other_payload = {
 "event_type": "ticket_updated",
 "data": {"ticket_id": "TKT-2023–001", "status": "pending"},
 "timestamp": "2023–10–27T10:30:00Z"
 }
 response_other = handle_new_ticket_webhook(other_payload)
 print("
Webhook Handler Response for other event:")
 print(json.dumps(response_other, indent=2))

Этот працоўнік обрабоцвае запуск падзеі новага тыкета і стварае запіт для керавальніка LLM. Такі падход заўсёды мае сваія проблемы, галоўная з яых — цэна і выконвальная спроможнасць.

Маршрутызацыя між мадэлямі

У масштабных сістэмах стратэгіі, якія выкарыстоўваюць адну мадэль, зазвычай не вытрымаюць тыччыны з боку вартоў і затрымакаў. Інтэлігентная маршрутызацыя ў шары інтэграцыі дапамагае збалансаваць гэтыя два факторы. Запыты можна адпраўляць да розных модэляў залежна ад складнасці задачы, неабходных затрымакоў і бюджэту.

Одна з практычных схем выкарыстоўвае дышэўскую, шырокую мадэль для простых задач, такіх як класыфікацыя дадзенняў, што значна зменшае вартасць обрабоцкі, і застаўляе моцную, дорогую мадэль для складных запытаў, такіх як стварэнне сложнага коду. Такі тонкі контроль дазволяе праграмаваць співвялічэнне можлівасцяў і вітрачанняя ў рэальны час, і гэта мае важлівэ значэнне, калі трэба кераваць квотамі API і лімітамі частоты ў працуючай сістэме.

Логіка маршрутацыі сама ў сабе ўскладненне, якое ўтварае частку інтэграцыйскага шару:

Хоць яна дадае архітэктурнай структуры большай складнасці, яна не дазволяе жаднаму адзінаму прадаўцу стаць вузькім месцам.

Складнасць эксплуатацыі вялікую ролю выграўае

Стабільная, прыемнае для адтрымкі архітэктура ШЫ мае большое значэнне, чым прагненне да самага новага модэлю. Калі праекты зазнаюць нявясці, зазвычай прычыной ёст тое, што недаўнае значэнне даўаецца эксплуатацыйной складнасці, якая стосуецца доступу да дадзэнняў, керавання і апрацоўкі асаблівых сітуацый.

Пераход з API-рамкі на шар мідлвэра дапамагае падтрымаць надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на надзею на н