웹사이트에 채팅봇 구현하기: 단계별 가이드
웹사이트 프로젝트에 채팅봇을 구현하는 방법은 세 부분으로 요약됩니다: 브라우저의 채팅 상자, API 키를 보관하는 작은 백엔드, 그리고 OpenAI 호환 엔드포인트로 호출하는 것입니다. 이 가이드는 작동하는 코드로 각 부분을 구축합니다.
업데이트

주요 포인트
- 브라우저 코드에서 API를 호출하지 마세요. 키를 서버에 보관하고 자체 /api/chat 엔드포인트를 노출하세요.
- API는 OpenAI 호환이므로 Base URL을 설정하고 uncensored 모델을 사용하면 표준 SDK가 작동합니다.
- 페이지가 빠르게 느껴지도록 스트리밍 응답을 사용하고 서버에서 기록을 제한하세요.
- 429 응답을 처리하고 방문자별 제한을 설정하세요. 키는 최대 8개의 동시 요청을 허용합니다.
아키텍처를 한눈에 보기
웹사이트 프로젝트에 채팅봇을 구현하는 일반적인 방법은 3단계 중계입니다. 방문자가 채팅 상자에 입력합니다. 페이지가 메시지를 자체 서버로 전송합니다. 서버가 비밀 키로 모델 API를 호출하고 답변을 전달합니다. 브라우저는 키를 보지 않습니다.
중요한 이유는 프론트엔드 JavaScript에 있는 모든 것은 공개된다는 것입니다. 키를 스크립트 태그에 넣으면 개발자 도구를 여는 누구나 키를 복사하여 잔액을 사용할 수 있습니다. 백엔드 라우트는 속도 제한, 이력 정리, 로깅 및 연령 확인을 추가할 수 있는 하나의 위치도 제공합니다. 완성된 페이지에 대한 긴 안내를 보려면 웹 채팅 튜토리얼을 참조하십시오.
1단계: 키를 얻고 엔드포인트 테스트
Google 또는 이메일과 비밀번호로 가입한 후 API 키 페이지에서 무료 체험을 청구하세요. 체험판은 7일 동안 유효한 $0.50 크레딧이며, 인원당 하나이며 결제가 필요하지 않습니다. 키를 코드에 저장하지 말고 환경 변수로 저장하세요.
앱 코드를 작성하기 전에 curl로 작동하는지 확인하세요:
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."}]}'첫 번째 호출은 모델을 나열하고 두 번째 호출은 채팅 완료 응답을 반환합니다. 둘 다 성공하면 키와 Base URL이 정확합니다. 401은 키가 잘못되었거나 Bearer 접두사가 누락되었음을 의미합니다.
2단계: 백엔드 라우트 작성
아래 예제는 Node 18 이상, Express 및 공식 openai 패키지를 사용합니다. npm install express openai로 설치하고 package.json에 "type": "module"을 설정하세요.
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"));여기서 세 가지 세부 사항이 실제 작업을 수행합니다. 서버는 메시지 목록을 자체적으로 재구성하므로 방문자가 가짜 시스템 메시지를 삽입할 수 없습니다. 마지막 10개의 메시지만 유지하고 각 메시지를 4,000자로 제한하여 비용을 제어합니다. 또한 알 수 없는 모든 것을 user로 매핑하여 역할을 항상 명시적으로 설정합니다.
3단계: 채팅 상자 구축
이것을 public/index.html에 넣으세요. 프레임워크가 없는 일반 JavaScript를 사용하므로 기존 템플릿에 붙여넣을 수 있습니다.
<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>모델 출력에 대해 textContent을 innerHTML 대신 사용하면 페이지에 마크업이 삽입되는 것을 방지할 수 있습니다. 모델이 출력을 잘 제어하더라도 이 습관을 유지하세요.
4단계: 제한 및 오류 처리
일반 키는 동시 8개 요청과 분당 300개 요청을 허용합니다. 체험 키는 동시 2개 요청과 분당 60개 요청을 허용합니다. 한도를 초과하면 API는 오류 코드와 함께 HTTP 429를 반환합니다: 분당 요청의 경우 rate_limited, 동시 요청이 많은 경우 concurrency. 일시적 과부하 시에도 Retry-After: 5 헤더와 함께 429를 반환합니다.
두 가지 실용적인 규칙이 따릅니다. 첫째, 지연 후 429를 짧은 백오프로 다시 시도하고 계속 실패하면 방문자에게 친절한 메시지를 표시하세요. 둘째, 스트리밍 요청은 스트림이 끝날 때까지 동시 요청 슬롯을 유지한다는 점을 기억하세요. 전체 키에서 10명의 방문자가 동시에 스트리밍하면 두 명이 거절되므로 서버에 작은 큐나 방문자별 제한을 추가하세요. 작은 사이트의 경우 IP를 키로 사용하는 간단한 메모리 카운터면 충분합니다.
응답 헤더는 디버깅에 도움이 됩니다: X-Request-Id은 지원팀에 연락할 때 호출을 식별하고, X-Balance-USD은 남은 크레딧을 보여줍니다. 요청 본문 제한은 8MB로 채팅에 필요한 양보다 훨씬 많으며 컨텍스트 창은 100,000 토큰입니다.
배포 시 주의할 점
위의 코드는 localhost에서 작동합니다. 다음은 실제 서버에 배포된 후에 나타나는 문제들입니다.
- 버퍼링 프록시. 일부 역방향 프록시는 스트리밍 응답을 완료할 때까지 기다리므로 응답이 한 번에 나타납니다. nginx를 사용하는 경우 채팅 엔드포인트에 대한 응답 버퍼링을 끄세요. 노트북에서만 테스트하지 말고 프로덕션에서 사용하는 동일한 프록시 체인을 통해 스트리밍을 테스트하세요.
- 저장소의 키. 키를 환경 변수 또는 비밀 저장소에 보관하고 로컬 env 파일을 무시 목록에 추가하세요. 키가 공개 저장소에 유출되면 새 키를 생성하고 이전 키의 사용을 중지하세요.
- 클라이언트 신뢰. 브라우저는 채팅 기록을 전송하므로 방문자가 편집할 수 있습니다. 이것이 2단계의 서버가 역할을 자체적으로 설정하고 메시지 길이를 제한하는 이유입니다. 클라이언트에서 시스템 메시지를 절대 수락하지 마세요.
- 교차 출처 요청. 페이지와 백엔드가 서로 다른 도메인에 있는 경우 브라우저는 서버가 올바른 CORS 헤더를 전송할 때까지 요청을 차단합니다. 하나의 오리진에서 둘 모두 제공하면 문제가 해결됩니다.
- 비용 폭주. 스크립트화된 방문자가 수백 개의 메시지를 보낼 수 있습니다. 서버에서 IP 또는 세션당 요청 수를 세고 수가 너무 많으면 거부하세요. 또한 예제처럼 메시지 길이를 제한하세요.
- 마크다운 및 링크. 모델은 종종 목록과 코드 펜스로 응답합니다. 렌더링할지 아니면 일반 텍스트를 표시할지 결정하고 응답 텍스트를 원시 HTML로 삽입하지 마세요.
마지막 확인은 모바일 레이아웃입니다. 공개 사이트의 대부분의 채팅 트래픽은 휴대폰에서 발생하므로 좁은 화면, 소프트웨어 키보드 열기 및 불안정한 연결로 테스트하세요. 스트림이 중간에 끊어지면 방문자가 스레드를 잃지 않고 다시 보낼 수 있어야 합니다.
나중에 봇 확장
기본 중계가 작동하면 동일한 엔드포인트로 더 많은 작업을 수행할 수 있습니다. API는 표준 OpenAI 기능을 지원하기 때문입니다. response_format을 {"type": "json_object"}로 설정하고 프롬프트에서 응답이 JSON이어야 한다고 명시하여 JSON 모드로 구조화된 출력을 요청할 수 있습니다. 이는 이름, 주제 및 긴급성 같은 필드로 자유 텍스트 메시지를 변환하는 리드 폼에 적합합니다.
함수 호출을 사용하면 모델이 서버에 함수를 실행하도록 요청할 수 있습니다. 예를 들어 주문 조회 또는 영업 시간 확인 등입니다. tools 목록을 전달하고 응답에서 tool_calls을 읽은 후 함수를 직접 실행한 다음 role: "tool" 메시지로 결과를 다시 전송하세요. 모델은 귀하의 데이터를 기반으로 최종 답변을 작성합니다. 이것이 웹사이트 봇이 추측이 아닌 실제 정보를 얻는 방법입니다.
샘플링 설정도 직접 조정할 수 있습니다. 낮은 온도는 사실 중심의 헬프데스크에 적합하고, 높은 온도는 스토리텔링에 적합합니다. 한 번에 한 가지 변경사항만 추가하고 동일한 5개 테스트 질문에서 결과를 비교하세요.
5단계: 봇을 다듬고 출시하기
시스템 프롬프트는 봇의 역할을 정의합니다. 봇의 정체성, 다루는 범위, 답변 길이를 지정하세요. 캐릭터에 성격이 있다면 페르소나 설계 페이지에서 더 자세히 알아보세요. 이 모델은 합법적인 성인 사용자를 위해 콘텐츠 거부 없이 답변하도록 튜닝되었으므로, 대상에 대한 가드레일은 직접 설정할 수 있습니다: 연령 확인, 신고 링크, 봇이 논의하지 않을 항목의 명확한 목록이 필요합니다. 미성년자가 관련된 성적 콘텐츠는 절대 허용되지 않습니다. 출시 전 책임 있는 사용 및 안전 장치 페이지를 확인하세요.
비용 측면에서 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.50을 지불합니다. 입력 토큰 1,200개와 출력 토큰 300개로 구성된 응답은 $0.00018 + $0.00015 = $0.00033이 듭니다. $20 충전으로 60,000회 이상의 응답을 처리할 수 있습니다. 충전 금액은 $20부터 $500까지이며, $50부터 +5%, $100부터 +10%, $200부터 +15%의 보너스가 제공되며 TRC20 USDT 또는 Base USDC로 결제됩니다. 크레딧은 만료되지 않습니다. 가격 책정 페이지에 세부 정보가 있으며 문서에는 함수 호출 및 JSON 모드 포함 모든 지원 매개변수가 나열되어 있습니다.
출시 전에 몇 번의 긴 대화로 테스트하고, 로그에서 429 응답이 발생하는지 확인하며, 서버가 이력을 잘라내는지 확인하십시오. 프롬프트는 학습에 사용되지 않지만, 여전히 방문자에게 저장하는 내용을 알려주어야 합니다.
더 많은 가이드
질문과 답변
브라우저 JavaScript에서 API를 직접 호출할 수 있나요?
가능하지만 권장하지 않습니다. 키가 모든 방문자에게 노출됩니다. 요청을 자체 서버로 라우팅하고 키를 환경 변수에 보관하세요.
어떤 언어와 SDK가 지원되나요?
모든 OpenAI SDK 또는 HTTP 클라이언트를 사용할 수 있습니다. Base URL을 https://api.uncensoredchatbotapi.com/v1,로 설정하고 키를 Bearer 토큰으로 사용하며 모델을 uncensored로 설정하세요. Python, Node 및 curl 모두 작동합니다.
브라우저에서 스트리밍이 작동하나요?
네. API는 stream을 true로 설정하여 SSE를 통해 스트리밍합니다. 예제는 fetch와 stream reader를 사용하여 텍스트를 서버로 중계합니다.
속도 제한에 도달하면 어떻게 되나요?
속도 제한 또는 동시 요청 한도에 도달하여 HTTP 429를 받으면 기다렸다가 다시 시도하세요. 일시적 과부하 시 Retry-After 헤더는 5초입니다.