Ограничения и най-добри практики
На тази страница
Технически ограничения при извикването на функции
Преди да започнете внедряването, трябва да разберете ограниченията на системата. Извикването на функции в Grok е мощно, но работи в рамките на специфични граници, които трябва да овладеете, за да изградите стабилни приложения.
Максимум 200 инструмента на заявка
API на Grok приема до 200 дефиниции на инструменти в една единствена заявка. Този лимит е щедър – повечето приложения използват само между 5 и 20. Но ако изграждате мащабируема система (плъгини, пазар на инструменти), трябва да го вземете предвид.
Всяка дефиниция на инструмент заема място в прозореца на контекста. По-конкретно:
- Един прост инструмент (2-3 параметъра) консумира около 50-100 токена
- Сложен инструмент (10+ параметъра, подробни описания) може да надхвърли 300 токена
- 200 сложни инструмента = 60 000 токена само за дефинициите
Ето защо трябва да бъдете стратегически: декларирайте само инструментите, които са релевантни за текущата заявка.
Моделът не гарантира валидност на аргументите
Grok полага максимални усилия да генерира аргументи, съответстващи на схемата, но не е непогрешим. Моделът може:
- Да генерира неправилен формат на дата
- Да предаде
string, когато се очакваinteger - Да пропусне задължително поле в редки случаи
- Да халюцинира стойности на enum, които не съществуват
Вашият код на страната на клиента трябва винаги да валидира получените аргументи преди изпълнението на функцията.
import json
def handle_tool_call(tool_call):
args = json.loads(tool_call.function.arguments)
# Validate before execution
if "city" not in args:
return {"error": "The city parameter is required"}
if not isinstance(args["city"], str):
return {"error": "city must be a string"}
return get_weather(args["city"], args.get("unit", "celsius"))
Обработка на грешки
Когато една функция се провали, трябва да върнете грешката към модела, вместо да прекратите работата тихо. Тогава моделът може:
- Да преформулира заявката си с коригирани параметри
- Да информира потребителя за проблема
- Да опита алтернативен инструмент
try:
result = search_database(query=args["query"])
return json.dumps(result)
except ConnectionError:
return json.dumps({
"error": "Database unavailable",
"suggestion": "Retry in a few seconds"
})
Винаги връщайте структуриран JSON, дори при грешка. Моделът разбира съобщенията за грешки и адаптира отговора си съответно.
Уникални и ясни имена
Имената на функциите трябва да бъдат уникални в списъка с инструменти. Ако два инструмента споделят едно и също име, поведението е неопределено – API може да отхвърли заявката или да игнорира един от тях.
Приемете последователна конвенция за именуване:
✅ Най-добри практики:
get_weather → извличане на данни
search_products → търсене
create_ticket → създаване
update_order_status → актуализиране
delete_draft → изтриване
❌ Избягвайте:
fn1, fn2 → неразбираеми
doStuff → твърде неясно
getWeatherData → camelCase (предпочитайте snake_case)
Описания: фактор №1 за качество
Качеството на описанието директно определя надеждността на извикването на функции. Ето сравнителна таблица:
| Слабо описание | Ефективно описание |
|---|---|
| "Search" | "Search for products by name, category, or price range in the e-commerce catalog" |
| "Send message" | "Send an email to a recipient. Requires a subject and message body. Does not support attachments." |
| "Calculate" | "Calculate the total price including tax from a pre-tax price and a VAT rate. Returns the amount in euros with 2 decimal places." |
Оптимизиране на броя инструменти
Вместо да декларирате 200 инструмента при всяка заявка, динамично избирайте тези, които наистина имат значение. Първият филтър е контекстът: ако потребителят говори за времето, зареждането на инструменти за фактуриране просто добавя шум – леко насочване нагоре по веригата (чрез ключови думи или първоначално обаждане за класификация) е достатъчно, за да се представят само релевантните семейства. Вторият филтър е ролята: агентът за поддръжка няма нужда от административни инструменти и премахването им е въпрос на прецизност, колкото и на сигурност. Третият е стъпката: в работен процес с няколко стъпки всяка фаза има свои собствени инструменти – зареждането им с напредването поддържа модела фокусиран върху това, което трябва да направи сега.
Ползата е двойна и незабавна: по-малко входни токени на заявка (дефинициите на инструменти Ви струват при всяко обаждане) и по-добра точност на избора – модел, избиращ между шест добре описани инструмента, рядко греши, докато същият модел, изправен пред двеста дефиниции, в крайна сметка обърква близки варианти.
Сигурност: никога не се доверявайте на модела
Извикването на функции е потенциален вектор за инжектиране. Злонамерен потребител може да формулира заявката си така, че да манипулира аргументите, предавани на функциите. Правила за сигурност:
- Валидирайте всички аргументи на страната на сървъра
- Ограничете правата: функция за четене не трябва да може да записва
- Регистрирайте обажданията: проследявайте всяко извикване на функция за одит
- Почиствайте входните данни: екранирайте специалните символи преди SQL/shell заявки
Ключови изводи
- Максимум 200 инструмента на заявка – но се стремете към 5-20 за ефективност
- Винаги валидирайте аргументите на страната на клиента преди изпълнение
- Връщайте грешки към модела в структуриран JSON
- Имената трябва да са уникални, в snake_case и ясни
- Подробните описания драстично подобряват надеждността
- Динамично избирайте релевантни инструменти за всяка заявка
- Никога не се доверявайте на аргументите без валидация