Премини към основното съдържание
Български— Изберете език
Меню

Автоматични цитати и най-добри практики

Урок 16 от 16 Обновен 30 юли 2026 г. Програмист
На тази страница
  1. Източници и надеждни отговори
  2. Как работят цитатите
  3. Показване на цитати във Вашето приложение
  4. Най-добри практики за продукция
  5. Контролен списък за внедряване
  6. Ключови изводи
  7. Проверете знанията си

Източници и надеждни отговори

Когато моделът използва търсене в уеб или търсене в 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
urlURL адрес на източника
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.