Hướng dẫn dùng AI

Cho mô hình tìm kiếm web qua API

Mô hình ngôn ngữ chỉ biết những gì có trong dữ liệu huấn luyện. Muốn nó trả lời về tin mới, giá cả, lịch thi năm nay, bạn cần cho nó tìm web. Với API của Anthropic, bạn chỉ khai báo công cụ tìm kiếm; API tự chạy tìm kiếm, mô hình tự quyết định khi nào cần tìm, và câu trả lời luôn kèm trích dẫn. Bài này giải thích cách khai báo, giới hạn, đọc kết quả, xử lý lỗi và tính chi phí, kèm đoạn Python.

Ý chính
  • Công cụ web_search là công cụ phía máy chủ: bạn khai báo, API tự chạy tìm kiếm, bạn không phải viết hàm tìm.
  • Mô hình tự quyết định có tìm hay không: tìm khi câu hỏi cần thông tin mới, thay đổi, ngoài dữ liệu huấn luyện; trả lời thẳng với kiến thức ổn định.
  • Câu trả lời luôn kèm trích dẫn: đường dẫn, tiêu đề, và đoạn trích tối đa 150 ký tự.
  • Giá 10 USD cho 1.000 lượt tìm, cộng token cho nội dung kết quả tìm. Đặt giới hạn số lượt và lọc tên miền để kiểm soát.

Bài này dựa trên trang Web search tool và Server tools trong tài liệu của Anthropic, đọc ngày 11/11/2026. Nên đọc trước bài tool use để hiểu công cụ phía khách khác công cụ phía máy chủ thế nào.

Công cụ phía máy chủ

Với công cụ do bạn tự viết, mô hình chỉ trả về yêu cầu gọi hàm, chương trình của bạn chạy hàm rồi gửi kết quả lại. Công cụ tìm kiếm web thì khác: Anthropic chạy nó. Bạn thêm công cụ vào danh sách công cụ của yêu cầu, và trong cùng một lời gọi, mô hình có thể tìm một hoặc nhiều lần, đọc kết quả, rồi viết câu trả lời cuối kèm nguồn.

Tài liệu mô tả khi nào mô hình tìm: khi câu hỏi phụ thuộc vào tin tức gần đây, giá cả, tỷ giá, điểm số, thông tin về tổ chức hay sản phẩm có thể đã đổi, hoặc khi người dùng yêu cầu tìm. Mô hình trả lời thẳng khi câu hỏi dựa trên kiến thức ổn định như toán, khái niệm lập trình, sáng tác, hay phân tích nội dung đã có trong hội thoại. Có thể điều chỉnh bằng chỉ dẫn hệ thống.

Có ba phiên bản công cụ: bản cơ bản; bản thêm lọc động, trong đó mô hình viết và chạy code để lọc kết quả trước khi đưa vào ngữ cảnh, giảm token với các yêu cầu tìm nhiều; và bản mới hơn thêm tùy chọn bỏ khối kết quả thô khỏi phản hồi. Ví dụ trong bài dùng bản cơ bản cho đơn giản.

Khai báo và giới hạn

Theo tài liệu, công cụ nhận vài tham số. Số lượt tối đa giới hạn số lần tìm trong một lượt trả lời; tài liệu cho biết câu hỏi một sự kiện thường cần 1 đến 3 lượt, câu hỏi so sánh nhiều đối tượng có thể cần 10 lượt trở lên. Lượt tìm thất bại vẫn tính vào giới hạn. Danh sách tên miền được phép hoặc bị chặn lọc nguồn kết quả, chỉ dùng một trong hai, viết tên miền không có giao thức. Vị trí người dùng (thành phố, vùng, mã quốc gia hai chữ, múi giờ) giúp kết quả sát địa phương hơn.

Quản trị viên tổ chức có thể tắt tìm kiếm web hoặc giới hạn tên miền trong trang quản lý; khi bị tắt, yêu cầu có công cụ này nhận lỗi 400.

Cho mô hình tìm web API chạy tìm kiếm, bạn chỉ khai báo công cụ 1. Khai báoweb_searchgiới hạn lượt, miền 2. Mô hình quyếtCó cần tìm khôngtin mới thì tìm 3. API tìmKết quả vào bàilỗi nằm trong khối 4. Trả lờiCó trích dẫnurl, tiêu đề 10 USD mỗi 1.000 lượt tìm, cộng token (11/11/2026)
Cho mô hình tìm web 1. Khai báoweb_searchgiới hạn lượt, miền 2. Mô hình quyếtCó cần tìm khôngtin mới thì tìm 3. API tìmKết quả vào bàilỗi nằm trong khối 4. Trả lờiCó trích dẫnurl, tiêu đề 10 USD mỗi 1.000 lượt tìm, cộng token (11/11/2026)
Hình 1. Cho mô hình tìm web: (1) khai báo công cụ web_search, giới hạn số lượt và tên miền; (2) mô hình quyết định có cần tìm không, thông tin mới thì tìm; (3) API chạy tìm, kết quả vào bài trả lời, lỗi nằm trong khối kết quả; (4) câu trả lời có trích dẫn đường dẫn và tiêu đề. Giá 10 USD mỗi 1.000 lượt tìm, cộng token, theo tài liệu ngày 11/11/2026.

Đọc phản hồi

Phản hồi gồm các khối theo thứ tự: chữ báo sẽ tìm, khối ghi truy vấn đã dùng, khối kết quả tìm (đường dẫn, tiêu đề, ngày cập nhật trang, nội dung được mã hóa), rồi các khối chữ của câu trả lời. Khối chữ nào dựa vào kết quả tìm thì có trích dẫn. Tài liệu ghi trích dẫn luôn được bật với tìm kiếm web, mỗi trích dẫn có đường dẫn, tiêu đề, và đoạn trích tối đa 150 ký tự; các trường này không tính vào token. Khi hiển thị đầu ra cho người dùng cuối, tài liệu yêu cầu kèm trích dẫn tới nguồn gốc.

Muốn hỏi tiếp trong cùng hội thoại, gửi lại nguyên các khối của trợ lý, gồm cả phần nội dung mã hóa; sửa hay bỏ phần đó sẽ bị lỗi 400.

Lỗi và tạm dừng

Hai điểm khác thường cần xử lý. Thứ nhất, lỗi tìm kiếm (quá giới hạn tốc độ, truy vấn quá dài, quá số lượt cho phép, lỗi nội bộ) không làm cả yêu cầu thất bại: API vẫn trả mã 200, lỗi nằm trong khối kết quả tìm dưới dạng một mã lỗi. Lượt tìm lỗi không bị tính tiền. Thứ hai, với lượt tìm dài, API có thể tạm dừng và trả lý do dừng là tạm dừng lượt; muốn tiếp tục, gửi lại nguyên tin của trợ lý trong yêu cầu mới.

Ví dụ bằng Python

Đoạn code dưới đây khai báo công cụ tìm kiếm với tối đa 3 lượt và tùy chọn danh sách tên miền được phép. Hàm hoi gọi mô hình; nếu bị tạm dừng thì gửi lại tin của trợ lý để tiếp tục, tối đa vài lần. Mô hình suy nghĩ trước khi trả lời và phần suy nghĩ tính vào giới hạn token đầu ra, nên giới hạn để rộng; hoi trả về cả lý do dừng cuối cùng, và nếu câu trả lời bị cắt hay bị từ chối thì chương trình báo là câu trả lời chưa trọn. Hàm doc_ket_qua gom chữ trả lời, danh sách nguồn không trùng đường dẫn, và các mã lỗi nằm trong khối kết quả. Hàm chi_phi cộng tiền lượt tìm (lấy từ trường đếm lượt tìm trong phần usage; trường này có thể trống, khi đó tính là không có lượt tìm) với tiền token.

"""Cho Claude tìm kiếm web qua công cụ phía máy chủ (web_search), đọc câu trả lời kèm nguồn, ước chi phí.

Theo tài liệu Anthropic (đọc 11/11/2026): API tự chạy tìm kiếm; câu trả lời luôn kèm trích dẫn (url, title, cited_text);
lỗi tìm kiếm nằm TRONG khối kết quả (mã HTTP vẫn 200); giá 10 USD cho 1.000 lượt tìm, cộng token như thường;
khi stop_reason là "pause_turn" thì gửi lại nguyên tin của trợ lý để tiếp tục; "max_tokens" (bị cắt, token suy nghĩ cũng
tính vào giới hạn này) hay "refusal" (từ chối) là câu trả lời chưa trọn, phải báo cho người dùng.
Bài dùng bản cơ bản web_search_20250305 (không cần chạy code để lọc kết quả).
Cài: python -m pip install anthropic ; đặt ANTHROPIC_API_KEY để chạy thật.
"""
import os
import sys

GIA_MOI_LUOT_TIM = 10 / 1000  # USD
# USD / 1 triệu token (vào, ra), theo trang Pricing xem lại ngày 15/11/2026. Haiku 5.5: giá cho prompt tới
# 100.000 token; lần gọi có prompt dài hơn (kết quả tìm cũng tính là token vào) trả 0,50 / 2,50.
GIA_VAO_RA = {"claude-sonnet-5-5": (2.0, 10.0), "claude-haiku-5-5": (0.10, 0.50)}


def cong_cu_tim(toi_da_luot=3, mien_cho_phep=None):
    cc = {"type": "web_search_20250305", "name": "web_search", "max_uses": toi_da_luot}
    if mien_cho_phep:
        cc["allowed_domains"] = list(mien_cho_phep)
    return cc


def doc_ket_qua(khoi):
    chu, nguon, loi = "", [], []
    for k in khoi:
        if k.type == "text":
            chu += k.text
            for c in getattr(k, "citations", None) or []:
                if c.url not in [n[0] for n in nguon]:
                    nguon.append((c.url, c.title))
        elif k.type == "web_search_tool_result" and not isinstance(k.content, list):
            loi.append(k.content.error_code)
    return chu, nguon, loi


def chi_phi(mo_hinh, so_luot_tim, token_vao, token_ra):
    vao, ra = GIA_VAO_RA[mo_hinh]
    return so_luot_tim * GIA_MOI_LUOT_TIM + (token_vao * vao + token_ra * ra) / 1e6


def hoi(client, cau_hoi, mo_hinh="claude-sonnet-5-5", mien_cho_phep=None, toi_da_tam_dung=3):
    tin = [{"role": "user", "content": cau_hoi}]
    khoi, so_tim, vao, ra = [], 0, 0, 0
    for _ in range(toi_da_tam_dung + 1):
        # Sonnet 5.5 suy nghĩ trước khi trả lời và token suy nghĩ tính vào max_tokens: câu trả lời mở cần giới hạn rộng.
        tl = client.messages.create(model=mo_hinh, max_tokens=16000, messages=tin,
                                    tools=[cong_cu_tim(mien_cho_phep=mien_cho_phep)])
        khoi += list(tl.content)
        dung_cong_cu = tl.usage.server_tool_use  # thư viện khai báo trường này có thể là None
        so_tim += dung_cong_cu.web_search_requests if dung_cong_cu else 0
        vao, ra = vao + tl.usage.input_tokens, ra + tl.usage.output_tokens
        if tl.stop_reason != "pause_turn":
            break
        tin = tin + [{"role": "assistant", "content": tl.content}]  # gửi lại nguyên văn để tiếp tục lượt
    chu, nguon, loi = doc_ket_qua(khoi)
    # Trả cả lý do dừng cuối: khác "end_turn" (bị cắt "max_tokens", bị từ chối "refusal", vẫn "pause_turn" sau mọi lần
    # tiếp tục) là câu trả lời chưa trọn.
    return chu, nguon, loi, chi_phi(mo_hinh, so_tim, vao, ra), so_tim, tl.stop_reason


def main(cau_hoi):
    if not os.environ.get("ANTHROPIC_API_KEY"):
        sys.exit("Chưa có ANTHROPIC_API_KEY. Đặt biến môi trường trước khi chạy.")
    import anthropic
    try:
        chu, nguon, loi, tien, so_tim, ly_do = hoi(anthropic.Anthropic(), cau_hoi)
    except anthropic.APIStatusError as e:
        sys.exit(f"API báo lỗi {e.status_code}: {e.message}")
    except anthropic.APIConnectionError:
        sys.exit("Không kết nối được tới API. Kiểm tra mạng rồi thử lại.")
    if ly_do != "end_turn":
        print(f"Lưu ý: câu trả lời chưa trọn, mô hình dừng vì {ly_do}.")
    print(chu)
    for i, (url, ten) in enumerate(nguon, 1):
        print(f"[{i}] {ten}: {url}")
    if loi:
        print("Lỗi tìm kiếm:", ", ".join(loi))
    print(f"{so_tim} lượt tìm, chi phí khoảng {tien:.4f} USD")


if __name__ == "__main__":
    main(" ".join(sys.argv[1:]) or "Kỳ thi Olympic AI quốc tế năm sau tổ chức ở đâu?")

Bộ thử đi kèm dựng hai phản hồi giả theo đúng cấu trúc trong tài liệu: lần đầu tìm một lượt rồi tạm dừng, lần sau gặp lỗi quá số lượt rồi trả lời kèm trích dẫn. Chương trình phải gửi lại đúng tin của trợ lý ở lần thứ hai, gom được một nguồn, ghi nhận một mã lỗi, và tính chi phí cho hai lượt tìm. Khi chạy thật, câu trả lời và nguồn do mô hình và kết quả tìm quyết định.

Chi phí và kiểm soát

Theo tài liệu, tìm kiếm web có giá 10 USD cho 1.000 lượt, cộng chi phí token cho nội dung kết quả tìm. Kết quả tìm được tính là token đầu vào, cả trong các vòng tìm của một lượt lẫn ở các lượt hội thoại sau. Một câu hỏi tốn 3 lượt tìm là 0,03 USD riêng phần tìm, chưa kể token. Với ứng dụng nhiều người dùng, đặt số lượt tối đa thấp, giới hạn tên miền cho đúng lĩnh vực, và chỉ bật công cụ cho loại câu hỏi thật sự cần thông tin mới.

Một ứng dụng mẫu: trợ lý tin tuyển sinh

Giả sử bạn làm trợ lý trả lời câu hỏi về kỳ thi, học bổng, lịch tuyển sinh. Thông tin này đổi theo năm nên cần tìm web. Một thiết kế hợp lý: danh sách tên miền được phép gồm trang chính thức của các trường, của bộ, của ban tổ chức kỳ thi; số lượt tìm tối đa 3; chỉ dẫn hệ thống yêu cầu luôn ghi năm của thông tin và nói rõ khi không tìm thấy nguồn chính thức. Câu trả lời hiển thị kèm danh sách nguồn có ngày cập nhật trang, để người đọc tự đánh giá thông tin còn mới không.

Ghi lại các truy vấn mô hình đã dùng và các tên miền xuất hiện trong kết quả. Sau một tuần, bạn biết câu hỏi nào hay phải tìm nhiều lượt, nguồn nào hay được dùng, và có thể tinh chỉnh danh sách tên miền cho phù hợp.

An toàn

Trang web là nội dung bên ngoài, có thể chứa chỉ dẫn lạ nhằm điều khiển mô hình. Nếu ứng dụng vừa tìm web vừa có công cụ làm việc quan trọng (gửi thư, ghi dữ liệu), áp dụng các lớp phòng thủ trong bài prompt injection là gì. Lọc tên miền về các nguồn tin cậy cũng giảm rủi ro này.

Cẩn thận
  • Bật tìm web cho mọi câu hỏi mà không giới hạn số lượt.
  • Giấu trích dẫn khi hiển thị câu trả lời cho người dùng.
  • Coi mã 200 là mọi lượt tìm đều thành công, bỏ qua lỗi trong khối kết quả.
  • Sửa hoặc bỏ phần nội dung mã hóa khi gửi lại lịch sử.
  • Cho mô hình vừa đọc web vừa có quyền gửi dữ liệu ra ngoài mà không duyệt.

Câu hỏi thường gặp

Khác gì tự gọi một API tìm kiếm bên ngoài?

Tự gọi thì bạn viết hàm tìm như công cụ phía khách và tự lo kết quả, trích dẫn. Công cụ phía máy chủ thì API lo hết, kèm trích dẫn.

Dùng trong xử lý theo lô được không?

Được, giá như gọi thường; tài liệu ghi lô có nhiều lượt tìm có thể chạy lâu hơn do bị điều tiết.

Làm sao mô hình tìm ít hơn?

Đặt số lượt tối đa và dặn trong chỉ dẫn hệ thống chỉ tìm khi thật cần.

Muốn đọc trọn một trang cụ thể thì sao?

Có công cụ đọc trang web riêng phía máy chủ để lấy nội dung một đường dẫn cụ thể.

Học tiếp

Nếu bạn muốn học Python và AI bài bản cùng giảng viên, tham khảo khóa học AI của Big-O Coding.

Muốn học bài bản cùng giảng viên?

Khóa AI – Introduction to Machine Learning: nền tảng Máy học từ thuật toán cơ bản đến Neural Networks và LLM, học bằng Python. Học thử buổi 1 miễn phí.

Xem Khóa AI

Nguồn tham khảo

Chia sẻ: Facebook LinkedIn
Nhắn Zalo tư vấnZalo Gọi 0937 401 483