Автоматични цитати и най-добри практики
На тази страница
Източници и надеждни отговори
Когато моделът използва търсене в уеб или търсене в X, API за отговори автоматично включва цитати в отговора. Тези цитати позволяват на Вашите потребители да проверят източниците и да изградят доверие в генерираните отговори.
Как работят цитатите
Цитатите се появяват в масива annotations на всеки елемент със съдържание:
{
"output": [{
"type": "message",
"content": [{
"type": "output_text",
"text": "According to the latest data, the AI market...",
"annotations": [
{
"type": "url_citation",
"url": "https://example.com/article",
"title": "AI Market Analysis in 2026",
"start_index": 35,
"end_index": 68
}
]
}]
}]
}
Полета на цитата
| Поле | Описание |
|---|---|
type | Винаги url_citation |
url | URL адрес на източника |
title | Заглавие на страницата източник |
start_index | Начална позиция в текста |
end_index | Крайна позиция в текста |
Показване на цитати във Вашето приложение
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest advancements in AI?",
tools=[{"type": "web_search"}]
)
text = response.output[0].content[0].text
annotations = response.output[0].content[0].annotations
# Изграждане на текст с бележки под линия
footnotes = []
for i, ann in enumerate(annotations, 1):
footnotes.append(f"[{i}] {ann.title} — {ann.url}")
print(text)
print("\n--- Sources ---")
for fn in footnotes:
print(fn)
В HTML
def render_with_citations(text, annotations):
# Сортиране по позиция (от край към начало, за да не се изместят индексите)
sorted_anns = sorted(annotations, key=lambda a: a.start_index, reverse=True)
html = text
for i, ann in enumerate(sorted_anns):
ref_num = len(sorted_anns) - i
link = f'<a href="{ann.url}" title="{ann.title}" target="_blank">[{ref_num}]</a>'
html = html[:ann.end_index] + link + html[ann.end_index:]
return html
Най-добри практики за продукция
1. Винаги проверявайте статуса
response = client.responses.create(...)
if response.status != "completed":
handle_error(response)
return
2. Обработка на празни отговори
if not response.output or not response.output[0].content:
return "The model did not generate a response."
text = response.output[0].content[0].text
3. Регистриране на метрики
За всяка заявка в продукционна среда регистрирайте:
response.idза проследимостusage.total_tokensза потреблениетоusage.cost_in_nano_usdза разходите- Време за отговор от страна на клиента
- Статус на отговора
4. Защитете Вашия API ключ
- Съхранявайте го в променлива на средата, никога в кода
- Използвайте мениджър на тайни в продукционна среда (Vault, AWS Secrets Manager)
- Ротирайте ключовете си редовно
- Никога не ги излагайте от страна на клиента (браузър)
5. Управление на генерираното съдържание
Отговорите на модела могат да съдържат неподходящо съдържание въпреки филтрите. Внедрете слой за модериране, ако показвате отговори публично.
6. Планирайте мащабируемост
- Използвайте стрийминг, за да намалите възприеманото време за изчакване
- Внедрете система за опашки за тежки заявки
- Кеширайте чести отговори
- Следете квотите си за ограничаване на честотата на заявките
Контролен списък за внедряване
- Таймаут, зададен на 3600 секунди
- Повторни опити с експоненциално забавяне
- Ограничаване на честотата от страна на клиента
- Регистриране на метрики (токени, разходи, латентност)
- Обработка на грешки (401, 429, 500, таймаут)
- Защитен API ключ
- Модериране на съдържанието, ако е необходимо
- Мониторинг на разходите и известия
- Прекъсвач на веригата за устойчивост
Ключови изводи
- Цитатите са автоматични, когато моделът използва
web_searchилиx_search - Те съдържат URL адреса, заглавието и позицията в текста
- Винаги проверявайте статуса и обработвайте празните отговори
- Защитете Вашия API ключ – никога в изходния код или от страна на клиента
- Внедрете регистриране, повторни опити, ограничаване на честотата и мониторинг, преди да преминете към продукция
Проверете знанията си
API за отговори в дълбочина: финалната проверка.
1. Какво предлага API за отговори в сравнение с Chat Completions?
Отговор: Съвременният формат: запазване на отговора от страна на сървъра (GET/DELETE, верижно свързване по ID), вградени инструменти и скорошни функции – API, върху което xAI фокусира еволюцията.
2. Как се свързва разговор във верига?
Отговор: Чрез препратка към предишния отговор: контекстът се запазва от страна на сървъра – няма нужда да изпращате цялата история отново при всеки ход.
3. Какво е криптирано разсъждение?
Отговор: Вътрешното разсъждение на модела, върнато в криптирана форма: може да се използва повторно в следващите ходове, без да бъде четимо – процесът на мислене пътува, конфиденциалността остава.
4. Какво позволява смесването на сървърни и клиентски инструменти?
Отговор: Комбиниране на вградени инструменти, изпълнявани от xAI (уеб търсене и др.), и Ваши собствени функции, изпълнявани от Вашия код – всеки инструмент на правилното място, оркестриран в една и съща заявка.
5. Кои са най-добрите практики за продукция?
Отговор: Обработка на таймаут и повторни опити, проследяване на таксуването (токени, инструменти) и използване на автоматични цитати за проверими отговори – надеждност и доверие заедно.
Запазване, инструменти, криптирано разсъждение, цитати: API за отговори е съвременната основа – тук се изграждат Вашите приложения с Grok.