Przejdź do głównej treści
Polski— Wybierz język
Menu

Automatyczne cytowania i najlepsze praktyki

Lekcja 16 z 16 Zaktualizowano 30 lipca 2026 Programista
Na tej stronie
  1. Odpowiedzi oparte na źródłach i wiarygodne
  2. Jak działają cytowania
  3. Wyświetlanie cytatów w aplikacji
  4. Najlepsze praktyki produkcyjne
  5. Lista kontrolna wdrożenia
  6. Kluczowe wnioski
  7. Sprawdź swoją wiedzę

Odpowiedzi oparte na źródłach i wiarygodne

Gdy model korzysta z wyszukiwania w sieci lub wyszukiwania w serwisie X, interfejs API Responses automatycznie dołącza do odpowiedzi cytowania. Pozwalają one użytkownikom zweryfikować źródła i budują zaufanie do generowanych odpowiedzi.

Jak działają cytowania

Cytowania pojawiają się w tablicy annotations każdego elementu treści:

{
  "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
        }
      ]
    }]
  }]
}

Pola cytowania

PoleOpis
typeZawsze url_citation
urlAdres URL źródła
titleTytuł strony źródłowej
start_indexPozycja początkowa w tekście
end_indexPozycja końcowa w tekście

Wyświetlanie cytatów w aplikacji

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

# Budowanie tekstu z przypisami
footnotes = []
for i, ann in enumerate(annotations, 1):
    footnotes.append(f"[{i}] {ann.title} — {ann.url}")

print(text)
print("\n--- Źródła ---")
for fn in footnotes:
    print(fn)

W HTML

def render_with_citations(text, annotations):
    # Sortowanie według pozycji (od końca do początku, aby uniknąć przesuwania indeksów)
    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

Najlepsze praktyki produkcyjne

1. Zawsze sprawdzaj status

response = client.responses.create(...)
if response.status != "completed":
    handle_error(response)
    return

2. Obsługa pustych odpowiedzi

if not response.output or not response.output[0].content:
    return "Model nie wygenerował odpowiedzi."
text = response.output[0].content[0].text

3. Rejestruj metryki

Dla każdego żądania produkcyjnego rejestruj:

  • response.id dla możliwości śledzenia
  • usage.total_tokens dla zużycia
  • usage.cost_in_nano_usd dla kosztów
  • Czas odpowiedzi po stronie klienta
  • Status odpowiedzi

4. Zabezpiecz swój klucz API

  • Przechowuj go w zmiennej środowiskowej, nigdy w kodzie
  • Używaj menedżera sekretów w środowisku produkcyjnym (Vault, AWS Secrets Manager)
  • Regularnie rotuj klucze
  • Nigdy nie udostępniaj ich po stronie klienta (przeglądarka)

5. Zarządzaj generowaną treścią

Odpowiedzi modelu mogą zawierać niewłaściwe treści mimo filtrów. Wdróż warstwę moderacji, jeśli wyświetlasz odpowiedzi publicznie.

6. Zaplanuj skalowalność

  • Używaj strumieniowania, aby skrócić postrzegany czas oczekiwania
  • Wdróż system kolejek dla ciężkich żądań
  • Buforuj częste odpowiedzi
  • Monitoruj limity przepustowości (rate limiting)

Lista kontrolna wdrożenia

  • Limit czasu (timeout) ustawiony na 3600 sekund
  • Ponawianie z wykładniczym opóźnieniem (exponential backoff)
  • Ograniczanie przepustowości po stronie klienta
  • Rejestrowanie metryk (tokeny, koszty, opóźnienia)
  • Obsługa błędów (401, 429, 500, timeout)
  • Bezpieczny klucz API
  • Moderacja treści w razie potrzeby
  • Monitorowanie kosztów i alerty
  • Wyłącznik awaryjny (circuit breaker) dla odporności

Kluczowe wnioski

  • Cytowania są automatyczne, gdy model używa web_search lub x_search
  • Zawierają adres URL, tytuł i pozycję w tekście
  • Zawsze sprawdzaj status i obsługuj puste odpowiedzi
  • Zabezpiecz swój klucz API – nigdy w kodzie źródłowym ani po stronie klienta
  • Przed przejściem do produkcji wdróż rejestrowanie, ponawianie, ograniczanie przepustowości i monitorowanie

Sprawdź swoją wiedzę

Interfejs API Responses w szczegółach: ostateczny sprawdzian.

1. Co oferuje interfejs API Responses w porównaniu do Chat Completions?

Odpowiedź: Nowoczesny format: trwałość odpowiedzi po stronie serwera (GET/DELETE, łączenie przez ID), wbudowane narzędzia i najnowsze funkcje – to API, na którym xAI koncentruje swój rozwój.

2. Jak połączyć rozmowę w ciąg?

Odpowiedź: Poprzez odwołanie się do poprzedniej odpowiedzi: kontekst jest przechowywany po stronie serwera – nie ma potrzeby ponownego wysyłania całej historii przy każdej turze.

3. Czym jest szyfrowane rozumowanie?

Odpowiedź: Wewnętrzne rozumowanie modelu zwracane w formie zaszyfrowanej: możliwe do wykorzystania w kolejnych turach bez możliwości odczytu – proces myślowy podróżuje, poufność pozostaje nienaruszona.

4. Na co pozwala mieszanie narzędzi serwerowych i klienckich?

Odpowiedź: Łączenie wbudowanych narzędzi wykonywanych przez xAI (wyszukiwanie w sieci itp.) z Twoimi własnymi funkcjami wykonywanymi przez Twój kod – każde narzędzie we właściwym miejscu, orchestrowane w tym samym żądaniu.

5. Jakie są najlepsze praktyki dla środowiska produkcyjnego?

Odpowiedź: Obsługa limitu czasu i ponawiania, śledzenie rozliczeń (tokeny, narzędzia) oraz wykorzystywanie automatycznych cytatów dla weryfikowalnych odpowiedzi – solidność i zaufanie w duecie.

Trwałość, narzędzia, szyfrowane rozumowanie, cytowania: interfejs API Responses to nowoczesny fundament – tutaj budujesz swoje aplikacje Grok.