Jak zaimplementować czatbota na stronie internetowej, krok po kroku
Zrozumienie, jak zaimplementować chatbota na stronie, sprowadza się do trzech elementów: okna czatu w przeglądarce, małego backendu, który przechowuje Twój klucz API, oraz wywołania endpointu kompatybilnego z OpenAI. Ten przewodnik buduje każdą z tych części z działającym kodem.
Zaktualizowano

Kluczowe punkty
- Nigdy nie wywołuj API z kodu przeglądarki. Trzymaj klucz na serwerze i udostępnij własną trasę /api/chat.
- API jest kompatybilne z OpenAI, więc standardowe SDK działają po ustawieniu base URL i użyciu modelu uncensored.
- Strumieniuj odpowiedzi, aby strona wydawała się szybka, i ogranicz historię na serwerze.
- Obsłuż odpowiedzi 429 i ustaw limit na odwiedzającego, ponieważ pełny klucz pozwala na 8 równoległych zapytań.
Architektura na jednym obrazku
Standardową metodą implementacji czatbota w projektach internetowych jest architektura pośrednicząca w trzech krokach. Odwiedzający wpisuje wiadomość w okno czatu. Twoja strona wysyła wiadomość do własnego serwera. Twój serwer wywołuje API modelu z Twoim tajnym kluczem i zwraca odpowiedź. Przeglądarka nigdy nie widzi klucza.
Ma to znaczenie, ponieważ wszystko w JavaScript po stronie klienta jest publiczne. Jeśli umieścisz klucz w tagu script, każdy, kto otworzy narzędzia deweloperskie, może go skopiować i wydać Twój saldo. Trasa backendowa daje Ci też jedno miejsce, aby dodać limity, przycinanie historii, logowanie i weryfikację wieku. Aby uzyskać dłuższy przewodnik po gotowej stronie, zobacz poradnik czatu webowego.
Krok 1: uzyskaj klucz i przetestuj endpoint
Zarejestruj się przez Google lub e-mail i hasło, a następnie odebierz darmowy kredyt próbny na stronie klucza API. Kredyt próbny wynosi $0,50 i jest ważny przez 7 dni, jeden na osobę, bez konieczności podawania danych płatności. Zapisz klucz jako zmienną środowiskową, a nie w kodzie.
Sprawdź, czy działa za pomocą curl przed napisaniem kodu aplikacji:
export API_KEY="YOUR_KEY"
curl https://api.uncensoredchatbotapi.com/v1/models -H "Authorization: Bearer $API_KEY"
curl https://api.uncensoredchatbotapi.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "uncensored", "messages": [{"role": "user", "content": "Say hello in five words."}]}'Pierwsze wywołanie wypisuje modele, a drugie zwraca uzupełnienie czatu. Jeśli oba się powiedą, klucz i Base URL są poprawne. Błąd 401 oznacza, że klucz jest nieprawidłowy lub brakuje prefiksu Bearer.
Krok 2: napisz trasę backendową
Poniższy przykład używa Node 18 lub nowszego, Express oraz oficjalnego openai pakietu. Zainstaluj je za pomocą npm install express openai i ustaw "type": "module" w package.json.
import express from "express";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredchatbotapi.com/v1",
apiKey: process.env.API_KEY,
});
const SYSTEM = "You are a helpful assistant for our website. Keep answers under 150 words.";
const app = express();
app.use(express.json({ limit: "100kb" }));
app.use(express.static("public"));
app.post("/api/chat", async (req, res) => {
const incoming = Array.isArray(req.body.messages) ? req.body.messages : [];
const history = incoming.slice(-10).map((m) => ({
role: m.role === "assistant" ? "assistant" : "user",
content: String(m.content).slice(0, 4000),
}));
try {
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "system", content: SYSTEM }, ...history],
stream: true,
});
res.setHeader("Content-Type", "text/plain; charset=utf-8");
for await (const chunk of stream) {
const text = chunk.choices[0]?.delta?.content;
if (text) res.write(text);
}
} catch (err) {
if (res.headersSent === false) res.status(err.status === 429 ? 429 : 502);
}
res.end();
});
app.listen(3000, () => console.log("Listening on http://localhost:3000"));Trzy szczegóły wykonują tu istotną pracę. Serwer samodzielnie odbudowuje listę wiadomości, więc odwiedzający nie może wstrzyknąć fałszywej wiadomości systemowej. Zachowuje tylko ostatnie 10 wiadomości i obcina każdą do 4000 znaków, co kontroluje koszty. I zawsze jawnie ustawia role, mapując wszystko, co jest nieznane, na user.
Krok 3: zbuduj pole czatu
Umieść to w public/index.html. Używa czystego JavaScript bez frameworków, więc możesz go wkleić do istniejącego szablonu.
<div id="log"></div>
<form id="form">
<input id="input" autocomplete="off" required />
<button>Send</button>
</form>
<script>
const messages = [];
const log = document.getElementById("log");
document.getElementById("form").addEventListener("submit", async (e) => {
e.preventDefault();
const input = document.getElementById("input");
messages.push({ role: "user", content: input.value });
log.insertAdjacentHTML("beforeend", "<p></p>");
log.lastElementChild.textContent = "You: " + input.value;
input.value = "";
const reply = document.createElement("p");
log.appendChild(reply);
const res = await fetch("/api/chat", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ messages }),
});
if (res.ok === false) { reply.textContent = "Busy, please try again in a moment."; return; }
const reader = res.body.getReader();
const decoder = new TextDecoder();
let full = "";
while (true) {
const { done, value } = await reader.read();
if (done) break;
full += decoder.decode(value, { stream: true });
reply.textContent = full;
}
messages.push({ role: "assistant", content: full });
});
</script>Użycie textContent zamiast innerHTML dla wyjścia modelu zapobiega wstrzykiwaniu znaczników do Twojej strony. Zachowaj tę praktykę nawet, gdy model zachowuje się poprawnie.
Krok 4: obsłuż limity i błędy
Pełny klucz pozwala na 8 równoległych zapytań i 300 zapytań na minutę. Klucz próbny pozwala na 2 równoległe i 60 na minutę. Gdy przekroczysz limit, API zwraca HTTP 429 z kodem błędu: rate_limited dla zapytań na minutę lub concurrency dla zbyt wielu naraz. Przy tymczasowym przeciążeniu zwraca również 429 z nagłówkiem Retry-After: 5.
Wynikają z tego dwie praktyczne zasady. Po pierwsze, ponów próbę po odpowiedzi 429 po opóźnieniu z krótkim backoffem i pokaż odwiedzającemu przyjazną wiadomość, jeśli błąd będzie się powtarzał. Po drugie, pamiętaj, że strumieniowane zapytanie zajmuje slot konkurencji do momentu zakończenia strumienia. Jeśli dziesięciu odwiedzających będzie strumieniować jednocześnie na pełnym kluczu, dwóch z nich zostanie odrzuconych, więc dodaj ma kolejkę lub limit na użytkownika na swoim serwerze. Prosty licznik w pamięci z kluczem po IP wystarczy dla małej strony.
Nagłówki odpowiedzi pomagają w debugowaniu: X-Request-Id identyfikuje wywołanie, jeśli skontaktujesz się ze wsparciem, a X-Balance-USD pokazuje Twój pozostały kredyt. Limit ciała zapytania to 8 MB, znacznie powyżej tego, czego potrzebuje czat, a okno kontekstu wynosi 100 000 tokenów.
Pułapki podczas wdrażania
Powyższy kod działa na localhost. Oto problemy, które się pojawiają, gdy trafi na prawdziwy serwer.
- Buforowanie przez proxy. Niektóre reverse proxy zatrzymują strumieniowane odpowiedzi do momentu ich zakończenia, więc odpowiedź pojawia się w całości naraz. Jeśli używasz nginx, wyłącz buforowanie odpowiedzi dla trasy czatu. Przetestuj strumieniowanie przez tę samą sieć proxy, której używasz w produkcji, a nie tylko na swoim laptopie.
- Klucze w repozytorium. Przechowuj klucz w zmiennej środowiskowej lub w magazynie sekretów i dodaj dowolny lokalny plik env do listy ignorowanych. Jeśli klucz kiedykolwiek znajdzie się w publicznym repozytorium, stwórz nowy i przestań używać starego.
- Ufanie klientowi. Przeglądarka wysyła historię czatu, więc odwiedzający może ją edytować. Dlatego serwer w kroku 2 sam ustawia role i obcina długość wiadomości. Nigdy nie akceptuj wiadomości systemowej od klienta.
- Zapytania cross-origin. Jeśli Twoja strona i backend znajdują się na różnych domenach, przeglądarka zablokuje zapytanie, dopóki Twój serwer nie wyśle odpowiednich nagłówków CORS. Serwowanie obu z jednego źródła rozwiązuje ten problem.
- Niekontrolowane koszty. Jeden zautomatyzowany odwiedzający może wysłać setki wiadomości. Licz zapytania na IP lub sesję na serwerze i odmawiaj, gdy liczba jest zbyt wysoka. Ogranicz również długość wiadomości, jak w przykładzie.
- Markdown i linki. Modele często odpowiadają listami i blokami kodu. Zdecyduj, czy renderujesz to, czy pokazujesz czysty tekst, i nigdy nie wstawiaj tekstu odpowiedzi jako surowego HTML.
Ostatnim sprawdzianem jest układ mobilny. Większość ruchu czatowego na publicznych witrynach pochodzi z telefonów, więc przetestuj na wąskim ekranie, z otwartą klawiaturą ekranową i niestabilnym połączeniem. Jeśli strumień się urwie w połowie, odwiedzający powinien móc ponownie wysłać wiadomość bez utraty wątku.
Rozszerzanie bota w przyszłości
Gdy podstawowe przekażenie zadziała, ta sama trasa może robić więcej, ponieważ API obsługuje standardowe funkcje OpenAI. Możesz poprosić o dane strukturalne w trybie JSON, ustawiając response_format na {"type": "json_object"} i dodając w promptie informację, że odpowiedź musi być w formacie JSON. Pasuje to do formularza pozyskania klienta, który przekształca wiadomość tekstową w pola takie jak imię, temat i pilność.
Wywoływanie funkcji pozwala modelowi poprosić Twój serwer o uruchomienie funkcji, np. wyszukania zamówienia lub sprawdzenia godzin otwarcia. Przekazujesz listę tools, odczytujesz tool_calls w odpowiedzi, uruchamiasz funkcję samodzielnie i zwracasz wynik jako wiadomość z role: "tool". Model następnie pisze ostateczną odpowiedź na podstawie Twoich danych. Tak bot na stronie uzyskuje prawdziwe informacje zamiast zgadywania.
Ustawienia próbkowania są również dla Ciebie dostępne. Niższa temperatura pasuje do działów wsparcia faktualnego, a wyższa do opowiadania historii. Dodawaj jedną zmianę naraz i porównuj wyniki na tych samych pięciu pytaniach testowych.
Krok 5: ukształtuj bota i uruchom
Prompt systemowy definiuje Twojego bota. Powiedz mu, kim jest, czym się zajmuje i jak długie powinny być odpowiedzi. Jeśli postać ma osobowość, notatki na projektowaniu persony idą głębiej. Ponieważ model jest dostrojony do odpowiadania bez odrzuceń treści dla prawnego użytku dorosłych, zapory dla Twojej grupy docelowej piszesz sam: potwierdzenie wieku, link do zgłoszenia i jasna lista tego, czego bot nie będzie omawiał. Treści seksualne z udziałem nieletnich są zawsze zabronione. Zobacz stronę na odpowiedzialnym użytkowaniu i środkach ostrożności przed uruchomieniem.
Jeśli chodzi o koszty, płacisz $0,15 za 1 mln tokenów wejściowych i $0,50 za 1 mln tokenów wyjściowych. Odpowiedź z 1200 tokenami wejściowymi i 300 wyjściowymi kosztuje $0,00018 plus $0,00015, co daje $0,00033. Doładowanie za $20 pokrywa ponad 60 000 takich odpowiedzi. Doładowania wynoszą od $20 do $500, z +5% od $50, +10% od $100 i +15% od $200, płatne w USDT na TRC20 lub USDC na Base. Kredyt nie wygasa. Na stronie z cenami znajdziesz szczegóły, a dokumentacja wymienia wszystkie obsługiwane parametry, w tym wywoływanie funkcji i tryb JSON.
Przed uruchomieniem przetestuj kilka długich rozmów, obserwuj logi pod kątem 429 i potwierdź, że Twój serwer przycina historię. Prompty nie są używane do trenowania, ale nadal powinieneś powiedzieć odwiedzającym, co przechowujesz.
Więcej przewodników
Pytania i odpowiedzi
Czy mogę wywołać API bezpośrednio z JavaScript w przeglądarce?
Możesz, ale nie powinieneś. Klucz API byłby widoczny dla każdego odwiedzającego. Przekieruj zapytania przez własny serwer i przechowuj klucz w zmiennej środowiskowej.
Które języki i SDK działają?
Dowolne SDK OpenAI lub klient HTTP. Ustaw base URL na https://api.uncensoredchatbotapi.com/v1, użyj klucza jako tokenu Bearer i ustaw model na uncensored. Działają Python, Node i curl.
Czy strumieniowanie działa w przeglądarce?
Tak. API strumieniuje przez SSE z ustawionym stream=true. Przykład przesyła tekst przez twój serwer za pomocą fetch i czytnika strumienia.
Co się stanie, gdy osiągnę limit zapytań?
Otrzymasz HTTP 429 z kodem rate_limited lub concurrency. Poczekaj i spróbuj ponownie. Przy tymczasowym przeciążeniu nagłówek Retry-After wynosi 5 sekund.
Twój klucz jest o jeden formularz stąd
Utwórz konto, skopiuj klucz, zmień base URL. To cała konfiguracja.