Hướng dẫn xây dựng chatbot bằng Python từ đầu

Phần lõi của một chatbot chỉ là lệnh gọi tới mô hình ngôn ngữ lớn (LLM) qua API, còn phần mất công nằm ở những thứ bọc quanh lệnh gọi đó: bộ nhớ hội thoại, streaming và cái giao diện để người khác dùng được.

Điều kiện tiên quyết:

• Cài đặt Python 3.10 trở lên.
• API Key từ OpenAI hoặc Anthropic.
• Môi trường dòng lệnh (Terminal/Command Prompt) đã sẵn sàng.

Phóng to: Chatbot viết bằng Python trả lời người dùng theo thời gian thực

Bước 1 — Dựng môi trường Python và khoá API

Dựng môi trường ảo trước để các thư viện của dự án này không đụng vào Python hệ thống.

# Khởi tạo và kích hoạt môi trường ảo
python -m venv chatbot_env
source chatbot_env/bin/activate  # Windows: chatbot_env\Scripts\activate
 
# Cài đặt thư viện lõi
pip install openai anthropic python-dotenv streamlit reflex tenacity

Tạo file .env tại thư mục gốc để quản lý biến môi trường:

OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key

Phóng to: Trang quản lý API key trên console của nhà cung cấp, nơi tạo khoá mới cho dự án

Kiểm tra: Chạy python --version để xác nhận phiên bản.

Bước 2 — Gọi API lần đầu và xác nhận nó chạy

Chọn một trong hai nhà cung cấp dưới đây để kiểm tra kết nối, vì bước này tách bạch được lỗi khoá API với lỗi code trước khi bạn viết thêm bất cứ dòng nào.

OpenAI (Sử dụng Responses API)

Đoạn dưới dùng model gpt-5.6 qua phương thức responses.create mới nhất.

from openai import OpenAI
import os
from dotenv import load_dotenv
 
load_dotenv()
client = OpenAI()
 
response = client.responses.create(
    model="gpt-5.6",
    input=[{"role": "user", "content": "Kết nối thành công?"}]
)
print(response.output_text)

Anthropic

Bản Anthropic gọi model claude-opus-5 cho phiên làm việc đầu tiên.

from anthropic import Anthropic
import os
 
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
 
message = client.messages.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Kết nối thành công?"}],
    model="claude-opus-5",
)
print(message.content[0].text)

Bước 3 — Cho chatbot nhớ hội thoại

Phóng to: Mỗi lượt hỏi mới phải gửi lại toàn bộ lịch sử hội thoại vì mô hình không tự nhớ

Lưu ý kỹ thuật: Với Responses API, hãy cộng dồn toàn bộ response.output vào lịch sử thay vì chỉ lấy phần text, để giữ lại các mục suy luận đã mã hoá (encrypted reasoning items) và tham số phase mà những mô hình lập luận cần đến; bỏ qua chỗ này thì code vẫn chạy trơn tru, không báo lỗi gì, nên bạn sẽ rất khó biết mình đã đánh rơi cái gì.

history = [{"role": "user", "content": "Chào, tôi là kỹ sư phần mềm."}]
 
# Gọi API lần 1
response = client.responses.create(
    model="gpt-5.6",
    input=history
)
 
# Cập nhật lịch sử: Giữ nguyên cấu trúc output để bảo toàn reasoning tokens
history += response.output
 
# Gửi câu hỏi tiếp theo dựa trên ngữ cảnh cũ
history.append({"role": "user", "content": "Tôi vừa giới thiệu tôi làm nghề gì?"})
next_response = client.responses.create(
    model="gpt-5.6",
    input=history
)
print(next_response.output_text)

Bước 4 — Bật streaming để phản hồi thời gian thực

Streaming hiển thị từng token ngay khi mô hình sinh ra, thay vì bắt người đọc ngồi đợi trọn câu trả lời.

Phóng to: Gọi thường phải đợi trọn câu trả lời, còn streaming đẩy từng token về ngay khi có

Streaming với OpenAI

API trả về một chuỗi sự kiện có kiểu. Lọc lấy response.output_text.delta để in phần văn bản mới sinh ra.

stream = client.responses.create(
    model="gpt-5.6",
    input=history,
    stream=True,
)
 
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)  # flush=True để đẩy dữ liệu ra terminal ngay lập tức

Streaming với Anthropic

Helper text_stream cho bạn duyệt dữ liệu đồng bộ, khỏi phải tự lắp các sự kiện lại với nhau:

with client.messages.stream(
    max_tokens=1024,
    messages=history,
    model="claude-opus-5",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Kiểm tra: Chữ hiện dần ra theo kiểu máy đánh chữ thay vì xuất hiện một lần.

Bước 5 — Đưa chatbot lên giao diện web bằng Streamlit

Streamlit không đọc file .env ở trên mà lấy khoá qua st.secrets. Tạo thêm file .streamlit/secrets.toml trong thư mục dự án trước khi chạy:

OPENAI_API_KEY = "khoá_openai_của_bạn"

Bọc client trong @st.cache_resource để Streamlit chỉ khởi tạo nó một lần thay vì mỗi lần rerun.

import streamlit as st
from openai import OpenAI
 
@st.cache_resource
def get_client():
    return OpenAI(api_key=st.secrets["OPENAI_API_KEY"])
 
client = get_client()
 
if "messages" not in st.session_state:
    st.session_state.messages = []
 
# Hiển thị lịch sử từ session_state
for msg in st.session_state.messages:
    with st.chat_message(msg["role"]):
        st.markdown(msg["content"])
 
if prompt := st.chat_input("Nhập yêu cầu..."):
    st.session_state.messages.append({"role": "user", "content": prompt})
    with st.chat_message("user"):
        st.markdown(prompt)
 
    with st.chat_message("assistant"):
        def stream_reply():
            events = client.responses.create(
                model="gpt-5.6",
                input=st.session_state.messages,
                stream=True,
            )
            for event in events:
                if event.type == "response.output_text.delta":
                    yield event.delta
 
        # st.write_stream nhận một generator và tự render hiệu ứng máy đánh chữ
        response_text = st.write_stream(stream_reply())
 
    st.session_state.messages.append({"role": "assistant", "content": response_text})

Vận hành: Chạy streamlit run [tên_file].py để kích hoạt giao diện web.

Phóng to: Giao diện chat Streamlit đang chạy trên trình duyệt với lịch sử hội thoại

Bước 6 — Xử lý lỗi, retry và quản lý token

Chạy thật thì mạng sẽ rớt và hạn mức sẽ bị chạm. Xử lý hai thứ đó, rồi mới tính đến chi phí token.

Tự động thử lại với Tenacity

from tenacity import retry, stop_after_attempt, wait_exponential
from openai import RateLimitError
 
@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
def call_api_with_retry(messages):
    try:
        return client.responses.create(model="gpt-5.6", input=messages)
    except RateLimitError:
        raise # Kích hoạt logic retry của tenacity

Quản lý cửa sổ ngữ cảnh

Khi hội thoại quá dài, cắt lát (slicing) để khỏi vượt giới hạn ngữ cảnh và khỏi đốt tiền oan, đổi lại chatbot sẽ quên sạch những gì nằm ngoài mấy lượt gần nhất:

# Giữ lại tối đa 10 lượt hội thoại gần nhất
if len(st.session_state.messages) > 10:
    st.session_state.messages = st.session_state.messages[-10:]

Chọn khung giao diện và khi nào cần đến agent SDK

Phóng to: So sánh Streamlit với Reflex và ranh giới khi nào nên chuyển sang agent SDK

Responses API là đủ cho một luồng chatbot đơn nhiệm, xử lý hội thoại trực tiếp, còn Agents SDK chỉ cần đến khi hệ thống phải quản lý nhiều AI agent, phải bàn giao tác vụ (handoffs) hoặc chạy code trong Sandbox cô lập. Nếu hỏi tôi thì cứ bắt đầu bằng Streamlit và Responses API, đến lúc nào chật chội thật rồi hãy đổi.

Xử lý các lỗi thường gặp

Việc nên làm ngay sau đó

Gắn thêm RAG (Retrieval Augmented Generation) với ChromaDB. RAG cho chatbot đọc tài liệu nội bộ của bạn (.pdf, .txt) rồi trả lời dựa trên đó, nên bớt ảo giác (hallucination) mà không phải huấn luyện lại mô hình.

Tài liệu tham khảo

• Python SDK — Claude Platform Docs
• Conversation state — OpenAI API
• Streaming API responses — OpenAI API
• Build a basic LLM chat app — Streamlit Docs
• Build LLM Chat App in Python — Reflex
• The 3 Best Python Frameworks To Build UIs for AI Apps — GetStream
• OpenAI Agents SDK
• Everyone is building LLM routers, we deprecated ours — Manifest