Automatyczne cytowania i najlepsze praktyki
Na tej stronie
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
| Pole | Opis |
|---|---|
type | Zawsze url_citation |
url | Adres URL źródła |
title | Tytuł strony źródłowej |
start_index | Pozycja początkowa w tekście |
end_index | Pozycja 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.iddla możliwości śledzeniausage.total_tokensdla zużyciausage.cost_in_nano_usddla 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_searchlubx_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.