Практичні нотатки: Агентський ШІ з LangChain — Частина 3: Виклик інструментів у LangChain
Покрокове пояснення до практичних нотаток: Агентський ШІ з LangChain — Частина 3: Виклик інструментів у LangChain: контракти, перевірки та слоти для коду для команд, які використовують цю схему.
Використовуйте цей документ як оновлену версію ідей з матеріалу «Агентні ШІ з LangChain — Частина 3: Виклик інструментів у LangChain», призначену для операторів: чіткі етапи, впорядковані блоки коду та примітки щодо відновлення, які зберігаються після передачі обов’язків. Етап Огляду найкраще функціонує, якщо його розглядати як вимірювану основу. Запишіть один ідеальний запис, один випадок збою та примітки щодо скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени або запити поруч із функціональними результатами. Відображення витрат на ранньому етапі запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ.
Концепції виклику інструментів
На етапі концепцій виклику інструментів необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Конфігурацію слід зберігати окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функціоналу мають знаходитися в одному місці, яке оператори можуть перевіряти, не читаючи весь код. Аутентифікація має відбуватися на шлюзі, а повторна авторизація — на рівні обробки даних. Один лише токен-носій не є межею окремого тенанту.
1. Конфігурації системи
На етапі 1 «Конфігурація системи» необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Необхідно документувати як шлях успішного виконання, так і шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Аутентифікація відбувається на шлюзі, а повторна авторизація — на рівні обробки даних. Один лише токен-носій не є межею окремого тенантства.
OPENAI_API_KEY="<Your OpenAI API Key>"
TAVILY_API_KEY=<Your TAVILY API Key>
class BaseConfig(BaseSettings):
OPENAI_API_KEY: Optional[str]
PINECONE_API_KEY: Optional[str]
TAVILY_API_KEY: Optional[str]
model_config = SettingsConfigDict(env_file=".env", extra="ignore")
2. Структура проекту
На етапі 2 «Структура проекту» необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Краще використовувати невеликі, перевірювані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру обробки даних. Аутентифікуйтеся біля шлюзу та повторно авторизуйтесь на рівні обробки даних. Один лише токен-носій не є межею окремого тенанта.
project/
|
├── tools
│ ├── get_sum.py # a simple LangChain tool example
| └── weather.py # get_weather LangChain tool using open source APIs
|
|── tool_call.py # implement tool-calling loop using LangChain tools
├── config.py # pydantic BaseConfig
├── .env # environment variable definition
├── .gitignore
└── requirements.txt # package requirements
3. Інструменти LangChain
На етапі 3 інструментів LangChain необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Призначте назви arteфактів, визначте критерії успіху та не допускайте беззвучного часткового завершення. Аутентифікуйтеся біля шлюзу та повторно авторизуйтесь на рівні обробки даних. Один лише токен-носій не є межею тенантства.
3.1. Що таке інструмент LangChain?
На етапі 3.1 «Що це?» необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість знову виконати крок, починаючи з відомої точки контролю, без необхідності вгадування прихованого стану. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Чітке відображення витрат заздалегідь запобігає несподіваним рахункам під час переходу з демо-середовища у спільні середовища. Аутентифікуйтеся біля шлюзу та повторно авторизуйтесь на рівні обробки даних. Один лише токен-носій не є межею окремого тенантства.
from langchain.tools import tool
@tool
def get_sum(a: int, b: int) -> int:
"""
get the summation of two integers
:param a: int, input integer
:param b: int, input integer
:return: int, the sum of a and b
"""
return a + b
3.2. Впровадження інструменту погоди
Для реалізації етапу 3.2 необхідно спочатку визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори мають мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Конфігурацію слід зберігати окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функціоналу мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Аутентифікація має відбуватися на шлюзі, а повторна авторизація — на рівні обробки даних. Один лише токен не є межею окремого тенанта.
3.3. Концепція виклику інструментів
Для концепції етапу 3×3 необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Необхідно документувати як шлях успішного виконання, так і шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Аутентифікація відбувається на шлюзі, а повторна авторизація — на рівні обробки даних. Один лише токен-носій не є межею окремого тенантства.
3.4. Виклик інструментів у LangChain
На етапі виклику інструментів 3 4 необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Краще використовувати невеликі, тестовані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на складну структуру обробки даних. Аутентифікуйтеся біля шлюзу та знову авторизуйтесь на рівні обробки даних. Один лише токен не є межею окремого сервісу. На етапі виклику інструментів 3 4 необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Записуйте час виконання та витрати на токени чи запити разом із функціональними результатами. Відображення витрат на ранньому етапі запобігає несподіваним рахункам під час переходу з демо-середовища до спільних.
3.4.1. Налаштування LLM та інструментів
Під час етапу налаштування 3 4 1 спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Зберігайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Зберігайте у кеші стабільні інструкції системи та схеми інструментів. Повторна передача ідентичних даних є поширеною причиною витрат ресурсів.
class WeatherAssistant:
def __init__(self):
# initialize llm
self.llm = ChatOpenAI(api_key=api_key, model="gpt-4o-mini", temperature=0)
# initialize a tool dictionary
self.tools = {"get_weather": get_weather,
"tavily_search": TavilySearch(max_results=3, tavily_api_key=TAVILY_API_KEY)}
# bind LangChain tools to llm
self.llm_with_tools = self.llm.bind_tools(list(self.tools.values()))
# initialize messages to store message list
self.messages = []
# System prompt
self.system_prompt = f"""You are a helpful assistant for question-answering tasks.
When users ask about weather, use the get_weather tool to get weather. For other questions,
use web_search. If you don't know the answer, just say that you don't know.
Be conversational and helpful in your responses."""
self.messages.append(SystemMessage(content=self.system_prompt))
3.4.2. Реалізація циклу виклику інструментів
Під час виконання етапу реалізації 3 4 2 спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Одночасно задокументуйте шлях успішного виконання та шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки. Фіксуйте назву інструменту, хеш аргументів, час відгуку та результат кожного виклику. Без цих записів дебагування агента може займати години.
async def chat(self, message: str):
# Wrap User message in a HumanMessage and add it to message list
self.messages.append(HumanMessage(content=message))
# Get AI response (it may or may not contain tool calls)
response = await self.llm_with_tools.ainvoke(self.messages)
self.messages.append(response)
# If there is any tool calls in the AI response
if response.tool_calls:
# process tool calls
for tool_call in response.tool_calls:
# retrieve function name from tool_call, then
# retrieve the tool from tool dictionary, and invoke it,
# append resulting tool message to message list
tool = self.tools[tool_call["name"]]
tool_result = await tool.ainvoke(tool_call)
self.messages.append(tool_result)
# Get final response after tool execution
final_response = await self.llm_with_tools.ainvoke(self.messages)
self.messages.append(final_response)
3.4.3 Тестування циклу
Під час виконання етапу тестування 3 4 3 спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається при частковій невдачі. Цей перелік допомагає зберігати чесність подальших змін у коді. Віддавайте перевагу невеликим, тестиованим одиницям перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну функцію, а не на складну послідовність операцій. Фіксуйте назву інструменту, хеш аргументів, час виконання та результат кожного виклику. Без цих даних пошук помилок займає години. Під час виконання етапу тестування 3 4 3 спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається при частковій невдачі. Цей перелік допомагає зберігати чесність подальших змін у коді. Записуйте час виконання та витрати на токени або запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ.
async def main():
print("hello tool calling!")
assistant = WeatherAssistant()
message = "What is the temperature in Tokyo?"
await assistant.chat(message)
for msg in assistant.messages:
msg.pretty_print()
if __name__ == "__main__":
asyncio.run(main())
4. Обмеження базового циклу виклику інструментів
Чотири обмеження цього етапу найкраще функціонують, якщо їх розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування дій перед розширенням обсягу роботи. Тримайте конфігурацію поза кодом додатку. Файли середовища, сховища конфіденційних даних та прапорці функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь граф. Робіть інструменти доступними з вузькими схемами та чіткими позначеннями побічних ефектів. Хостам потрібно знати, які виклики змінюють стан, перш ніж вони автоматично схвалюють їх.
5. Підсумок
Етап 5 «Заключний підсумок» найкраще функціонує, якщо його розглядати як вимірювану поверхню. Зафіксуйте один ідеальний варіант роботи, один випадок невдачі та примітку щодо скасування змін перед розширенням обсягу роботи. Документуйте як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки. Зробіть інструменти з вузькими схемами та чіткими позначеннями побічних ефектів доступними; хостам потрібно знати, які виклики змінюють стан, перш ніж вони автоматично схвалять їх.
Чек-лист операцій
Під час роботи над етапом чек-листу операцій спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається при частковій невдачі. Цей чек-лист забезпечує прозорість подальших змін у коді. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового завершення роботи.
Записуйте назву інструменту журналізації, хеш аргументів, час затримки та результат кожного виклику. Без цих даних процес налагодження триває годинами.
Зберігайте стан графа у простому та типованому вигляді. Вкладені структури приховують інформацію про те, який вузол заповнив яке поле, що ускладнює продовження роботи після перерв.
Коли дозволяє бюджет, додайте тест на базову функціональність, який перевіряє критичний шлях у середовищі CI за допомогою фікстур, а не реальних платних API.
Одночасно задокументуйте як успішний, так і відновлювальний шляхи роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.
Перед підвищенням версій стеку заморозьте їх, збережіть ідеальний запис дій для критичного шляху та підтвердьте кроки для скасування змін. У спільних середовищах необхідні обмеження на частоту запитів, перевірки прав доступу та чіткий власник для зміни секретів. Віддавайте перевагу надійності перед креативними одноразовими демонстраціями.
Примітка до пакету d7ca1ebeb899: не включайте ключі постачальників у репозиторій, встановіть ліміт токенів на сеанс та зберігайте транскрипції поруч із фіксами для оцінки, щоб подальша заміна моделей залишалася порівнянною.