Hugging Face smolagents + Scrapeless MCP: Xây dựng một Trình thu thập dữ liệu web AI bằng Python

Tóm tắt ngắn gọn:

• Một tác nhân Hugging Face nhận 21 công cụ web trực tiếp từ một điểm cuối MCP. Chỉ cần chỉ định ToolCollection.from_mcp đến https://api.scrapeless.com/mcp sẽ cung cấp cho một CodeAgent khả năng điều khiển trình duyệt, thu thập dữ liệu trang, và tìm kiếm Google và Xu hướng, trong khi việc xử lý, định tuyến proxy và chống phát hiện vẫn nằm phía máy chủ.
• Đường dẫn được lưu trữ hoàn toàn bằng Python. HTTP có thể truyền tải với tiêu đề x-api-token thay thế bất kỳ quy trình máy chủ cục bộ nào — không cần Node.js, chỉ một lệnh pip install "smolagents[mcp]".
• Bề mặt công cụ hoạt động trước khi mô hình hoạt động. Một cuộc gọi hàm đơn giản tới scrape_markdown trả về một trang sống dưới dạng markdown sạch — 4,249 ký tự cho trang demo trong hướng dẫn này — vì vậy bạn có thể kiểm tra kết nối chỉ với một khóa API Scrapeless.
• Một công cụ AI thu thập dữ liệu dựa trên ý nghĩa, chứ không phải dựa trên bộ chọn. Tác nhân đọc markdown và trả về các trường bạn yêu cầu, vì vậy một thiết kế lại trang web có thể làm gãy kịch bản bộ chọn CSS thường không tốn kém cho bạn.
• Yêu cầu tiên quyết duy nhất là một khóa mô hình. Liệt kê công cụ, gọi công cụ trực tiếp, và xây dựng tác nhân đều hoạt động mà không cần một khóa; chỉ có vòng lặp suy luận là cần một mã thông báo Hugging Face hoặc nhà cung cấp được hỗ trợ khác.
• Miễn phí để bắt đầu. Tạo khóa API của bạn trên gói miễn phí tại app.scrapeless.com.

Tính năng của tích hợp này

Một công cụ thu thập dữ liệu dựa trên bộ chọn là một cược rằng trang mục tiêu không bao giờ thay đổi, và cược đó thường thua. Một công cụ AI thu thập dữ liệu có một quan điểm khác: lấy trang dưới dạng văn bản sạch, để một mô hình ngôn ngữ lấy ra các trường mà bạn muốn, và ngừng quan tâm đến việc giá nằm trong div nào trong tuần này.

smolagents là thư viện tác nhân nhỏ của Hugging Face — các tác nhân của nó viết Python để gọi công cụ thay vì phát ra các cuộc gọi công cụ JSON. Điều mà nó thiếu là một cách để kết nối với web trực tiếp. Điều đó là công việc của Giao thức Ngữ cảnh Mô hình: thông số kỹ thuật Giao thức Ngữ cảnh Mô hình định nghĩa cách mà một máy chủ quảng cáo các công cụ có kiểu mà mọi khách hàng có thể liệt kê và gọi. Nếu giao thức này còn mới với bạn, thì phần giới thiệu về MCP là gì và nó hoạt động như thế nào sẽ bao quát khái niệm một cách toàn diện.

Kết nối hai thứ lại với nhau và bạn có một công cụ AI thu thập dữ liệu lập trình trong vài chục dòng Python: smolagents cung cấp vòng lặp suy luận, máy chủ Scrapeless MCP cung cấp việc lấy dữ liệu, xử lý và tìm kiếm dưới dạng các công cụ có thể gọi. Hướng dẫn này xây dựng công cụ thu thập dữ liệu đó từng bước và cho thấy chính xác các phần nào chạy chỉ với một khóa Scrapeless.

Tại sao là Scrapeless MCP

Máy chủ Scrapeless MCP công khai cơ sở hạ tầng thu thập dữ liệu dưới dạng 21 công cụ có kiểu, và công việc nặng được thực hiện trên máy chủ, không phải trong quy trình của bạn. scrape_html, scrape_markdown, và scrape_screenshot thu thập các trang đơn lẻ dưới các hình thức khác nhau. Mười sáu công cụ browser_* điều hành các phiên trình duyệt đám mây trên Trình duyệt Thu thập dữ liệu — một trình duyệt đám mây chống phát hiện được phát triển dựa trên Chromium — cho các công việc mà tác nhân phải nhấp, gõ và cuộn. google_search và google_trends phục vụ việc khám phá.

Ba thuộc tính quan trọng cho việc xây dựng này:

• Một khóa, vận chuyển lưu trữ. Khóa API Scrapeless giống như phần còn lại của nền tảng xác thực điểm cuối MCP. Quy trình Python của bạn không bao giờ khởi động một trình duyệt hoặc máy chủ Node.
• Khả năng kiểm tra không phụ thuộc vào mô hình. Các công cụ liệt kê và thực thi mà không cần bất kỳ LLM nào trong vòng lặp, vì vậy việc tích hợp có thể được chứng minh từng lớp thay vì được gỡ lỗi thông qua suy luận của tác nhân.
• Một con đường trích xuất theo markdown trước. Việc ghi lại markdown của một trang chỉ là một phần nhỏ so với kích thước của HTML gốc của nó, có nghĩa là ít token hơn cho mỗi lần trích xuất và ít tiếng ồn hơn cho mô hình để đọc qua. scrape_markdown trả về chính xác điều đó.

Điểm cuối giống nhau cũng có thể kết nối với LangChain nếu đó là ngăn xếp của bạn — hướng dẫn LangChain + Scrapeless MCP đi qua cùng một bề mặt từ phía bộ điều hợp.

Yêu cầu tiên quyết

• Python 3.10 hoặc mới hơn — các chạy trong hướng dẫn này đã sử dụng Python 3.12.
• Một khóa API Scrapeless từ bảng điều khiển — tài liệu developer docs đề cập đến việc tạo khóa và tham chiếu điểm cuối.
• Chỉ cho vòng đi vòng lại của tác nhân cuối cùng: một mã thông báo Hugging Face (hoặc thông tin xác thực cho bất kỳ nhà cung cấp mô hình nào mà smolagents hỗ trợ). Mọi bước trước đó đều hoạt động mà không cần mã thông báo này.

Cài đặt và cấu hình

Một gói với một tùy chọn bổ sung cung cấp thư viện tác nhân và các thành phần khách hàng MCP. Các phiên bản này là những phiên bản mà hướng dẫn này được viết dựa trên — smolagents 1.26.0, mcp 1.27.1, mcpadapt 0.1.20:

pip install "smolagents[mcp]==1.26.0"

Xuất khóa của bạn để các tập kịch bản có thể đọc từ môi trường thay vì từ mã nguồn:

export SCRAPELESS_API_KEY="sk_your_key_here"

Kết nối qua HTTP có thể phát và liệt kê các công cụ

Kết nối là một từ điển, không phải là một tệp cấu hình. ToolCollection.from_mcp chấp nhận cùng các tham số như khách hàng HTTP có thể phát bên dưới, vì vậy URL điểm cuối, tên phương tiện vận chuyển, và tiêu đề xác thực di chuyển trong cùng một chuỗi.

# connect_and_list.py — bắt tay với máy chủ Scrapeless MCP, liệt kê các công cụ
import os

from smolagents import ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    names = sorted(tool.name for tool in tc.tools)
    print(f"Số công cụ: {len(names)}")
    print("\n".join(names))

Quản lý ngữ cảnh sở hữu vòng đời kết nối: nó thực hiện bắt tay MCP khi vào và ngắt kết nối sạch sẽ khi ra. Một tham số xứng đáng được đề cập: đặc tả công cụ MCP cho phép máy chủ trả lại kết quả dưới dạng văn bản bình thường hoặc dưới dạng nội dung có cấu trúc, và các công cụ Scrapeless trả lại văn bản — vì vậy hãy truyền structured_output=False một cách rõ ràng. smolagents 1.26 cảnh báo mỗi khi tham số này bị bỏ qua, vì mặc định của nó dự kiến sẽ đảo ngược trong một bản phát hành tương lai.

Một bắt tay chính xác in ra Số công cụ: 21 tiếp theo là các tên: mười sáu công cụ browser_*, google_search, google_trends, scrape_html, scrape_markdown, và scrape_screenshot.

Một tuyến đường stdio cũng tồn tại, cho các khách hàng muốn khởi động một quy trình máy chủ cục bộ — cùng 21 công cụ nhưng với một vòng đời khác:

{
  "mcpServers": {
    "scrapeless": {
      "command": "npx",
      "args": ["-y", "scrapeless-mcp-server"],
      "env": { "SCRAPELESS_KEY": "sk_your_key_here" }
    }
  }
}

Đối với một bản xây dựng chỉ bằng Python, HTTP có thể phát là con đường ngắn hơn: không có gì để cài đặt ngoài pip, không có gì để chạy liên tục.

Lấy khóa API của bạn trong gói miễn phí: app.scrapeless.com

Gọi scrape_markdown trước khi bất kỳ mô hình nào được liên quan

Mỗi công cụ trong bộ sưu tập là một đối tượng Tool có thể gọi của smolagents, vì vậy lớp thu thập dữ liệu có thể được sử dụng trực tiếp — không có khóa tác nhân hoặc mô hình nào liên quan:

# call_tool.py — thực hiện một công cụ MCP như một cuộc gọi hàm bình thường
import json
import os

from smolagents import ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    tools = {tool.name: tool for tool in tc.tools}
    raw = str(tools["scrape_markdown"](url="https://quotes.toscrape.com/"))
    # Công cụ được lưu trữ trả lại trang dưới dạng chuỗi JSON được trích dẫn
    # sau một dòng "Response:" — giải mã nó để lấy nội dung markdown.
    body = raw.split("\n\n", 1)[1] if raw.startswith("Response:") else raw
    text = json.loads(body) if body.startswith('"') else body
    print(f"scrape_markdown trả về {len(text):,} ký tự markdown")
    print(text[:160])

Chống lại trang demo trích dẫn, điều này trả về 4,249 ký tự markdown, bắt đầu với tiêu đề trang và câu trích dẫn đầu tiên — văn bản có thể đọc được với chrome của trang đã bị xóa. Cuộc gọi duy nhất đó là toàn bộ lớp thu thập của trình thu thập. Mọi thứ sau đó là sự diễn giải.

Gắn các công cụ vào một CodeAgent

Liên kết bộ sưu tập với một tác nhân là một bộ khởi tạo, và nó hoạt động trước khi bất kỳ cuộc gọi mô hình nào được thực hiện. Đối tượng tác nhân chỉ mục mỗi công cụ MCP theo tên bên cạnh final_answer tích hợp sẵn của nó:

# attach_agent.py — đưa bề mặt công cụ MCP cho một CodeAgent của smolagents
import os

from smolagents import CodeAgent, InferenceClientModel, ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    model = InferenceClientModel(model_id="Qwen/Qwen2.5-72B-Instruct")
    agent = CodeAgent(tools=[*tc.tools], model=model, add_base_tools=False)
    print(sorted(agent.tools.keys()))

add_base_tools=False giữ cho hộp công cụ chỉ bao gồm các công cụ MCP và final_answer được tích hợp sẵn trong tác nhân. Đối với một công cụ thu thập thông tin chỉ cần lấy trang và không hơn gì nữa, bạn có thể thu hẹp nó hơn nữa — chỉ cần truyền công cụ bạn muốn, như trong tools=[t for t in tc.tools if t.name == "scrape_markdown"] — và mô hình sẽ không thể lang thang vào các phiên trình duyệt hoặc các cuộc gọi tìm kiếm không cần thiết. Một hộp công cụ nhỏ hơn cũng có nghĩa là một lời nhắc hệ thống nhỏ hơn và ít sai lầm hơn từ mô hình.

Sử dụng theo lời nhắc: quy trình chạy AI scraper

Bước trích xuất là một lời nhắc, không phải là một trình phân tích. Bạn nói với tác nhân trang nào để đọc và các trường nào để trả về, và tác nhân quyết định gọi scrape_markdown, đọc kết quả và tổng hợp câu trả lời — smolagents mô tả từng công cụ cho mô hình với các đầu vào kiểu, cùng cấu trúc mà định nghĩa JSON Schema cho các ràng buộc trường có thể đọc được bằng máy.

Ghi chú: Bước cuối cùng này là một khoảng trống cần thiết trong hướng dẫn này — vòng đi vòng lại của tác nhân cần một nhà cung cấp mô hình. Đặt HF_TOKEN với mã thông báo Hugging Face (hoặc cấu hình một nhà cung cấp khác mà smolagents hỗ trợ) trước khi chạy. Mỗi khối trên chỉ chạy với khóa Scrapeless.

# run_scraper.py — vòng đi vòng lại của mô hình (cần HF_TOKEN hoặc một nhà cung cấp khác)
result = agent.run(
    "Gọi scrape_markdown trên https://quotes.toscrape.com/ và trả về một mảng JSON "
    "của các câu trích dẫn trên trang. Mỗi mục phải có chính xác các khóa này: "
    "text (chuỗi), author (chuỗi), tags (mảng các chuỗi). "
    "Chỉ trả về mảng JSON, không bình luận."
)
print(result)

Hình dạng lời nhắc kiểm soát hình dạng đầu ra. Đặt tên chính xác các khóa và kiểu, yêu cầu "chỉ có mảng JSON", và giữ một trang mỗi lần chạy sẽ cho bạn đầu ra mà bạn có thể json.loads và xác thực xuống dòng. Khi một trường bị thiếu trên trang, hướng dẫn tác nhân sử dụng null thay vì tự sáng tạo một giá trị — các mô hình tự tin lấp đầy khoảng trống trừ khi được bảo không làm vậy.

Những gì bạn nhận được

Từ lớp lấy dữ liệu, bạn nhận được markdown dưới dạng chuỗi: tiêu đề trang dưới dạng tiêu đề, văn bản liên kết được giữ nguyên trong dấu ngoặc, văn bản thân bài theo thứ tự đọc. Đoạn ký tự 4,249 từ trang trích dẫn bắt đầu như sau:

# [Quotes to Scrape](https://quotes.toscrape.com/)

[Đăng nhập](https://quotes.toscrape.com/login)

“Thế giới mà chúng ta đã tạo ra là một quá trình tư duy của chúng ta.

Từ lần chạy tác nhân, bạn nhận được bất kỳ hợp đồng nào mà lời nhắc của bạn đã thực thi — ở đây, một mảng JSON của các đối tượng {text, author, tags}, một đối với mỗi câu trích dẫn trên trang. Giá trị của sự sắp xếp sẽ xuất hiện vào ngày trang mục tiêu thay đổi tên lớp: markdown vẫn chứa các câu trích dẫn, lời nhắc vẫn đặt tên các trường, và trình thu thập vẫn trả về cùng một lược đồ trong khi một kịch bản dựa trên bộ chọn không trả về gì cả.

Kết luận

Việc tích hợp gồm ba bước nhỏ: chỉ định ToolCollection.from_mcp tại điểm cuối được lưu trữ, xác minh lớp lấy dữ liệu với một cuộc gọi scrape_markdown trực tiếp, sau đó liên kết các công cụ với CodeAgent và để một lời nhắc thực hiện việc trích xuất. Mỗi lớp đều có thể kiểm tra một mình, chỉ có lớp cuối cùng cần một khóa mô hình, và phần có khả năng bị hỏng nhất trong một công cụ thu thập thông tin cổ điển — việc phân tích — là phần mà mô hình tiếp thu.

Sẵn sàng để cho tác nhân của bạn có một bề mặt web thực sự?

Điểm cuối MCP xác thực với cùng một khóa API như phần còn lại của nền tảng Scrapeless — các gói và khối lượng đi kèm có mặt trên trang giá cả. Tạo một khóa trên gói miễn phí tại app.scrapeless.com và kịch bản bắt tay ở trên sẽ in ra 21 công cụ của bạn trong chưa đầy một phút.

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

Q: AI scraper là gì?

AI scraper là một công cụ thu thập thông tin sử dụng mô hình ngôn ngữ cho bước trích xuất thay vì quy tắc phân tích viết tay. Một công cụ thu thập thông tin thông thường kết hợp việc lấy và phân tích theo một cấu trúc trang cụ thể; một AI scraper lấy trang dưới dạng văn bản và yêu cầu một mô hình trả về các trường được đặt tên, điều này vẫn hoạt động thông qua các thay đổi bố cục có thể phá vỡ các bộ chọn.

Q: Tôi có cần một mã thông báo Hugging Face để gọi các công cụ Scrapeless không?

Không. Liệt kê các công cụ, gọi scrape_markdown trực tiếp và xây dựng CodeAgent đều xác thực chỉ với khóa API Scrapeless. Mã thông báo Hugging Face (hay của nhà cung cấp khác) chỉ cần cho đúng một việc: vòng đi vòng lại lý do agent.run().

Q: Tôi nên kết nối qua HTTP có thể luồng hoặc stdio?

Sử dụng HTTP có thể luồng cho các dự án Python: nó không cần quá trình cục bộ và xác thực với tiêu đề. Giao thông stdio (npx -y scrapeless-mcp-server, xác thực thông qua biến môi trường SCRAPELESS_KEY) phù hợp với các khách hàng MCP trên máy tính để bàn quản lý chính các quy trình máy chủ. Cả hai giao thông đều mở rộng cùng một bề mặt công cụ.
H: Đại lý có thể chỉ sử dụng một công cụ thay vì tất cả 21 công cụ không?

Có. Lọc bộ sưu tập trước khi xây dựng đại lý — tools=[t for t in tc.tools if t.name == "scrape_markdown"] — và mô hình chỉ nhìn thấy công cụ đó. Đối với các trình thu thập đơn mục đích, đây là hình dạng được khuyến nghị: thông báo hệ thống thu nhỏ lại và mô hình không thể bắt đầu các phiên trình duyệt mà bạn không bao giờ dự định.

H: Thế còn các trang nặng JavaScript hoặc các trang sau thử thách chống bot thì sao?

Việc kết xuất diễn ra ở phía máy chủ, vì vậy mã Python của bạn không thay đổi. scrape_html và scrape_markdown xử lý các trang cần thực thi JavaScript, và các công cụ browser_* điều khiển các phiên trình duyệt đám mây đầy đủ cho các luồng cần nhấp chuột hoặc nhập liệu. Định tuyến proxy và chống phát hiện là một phần của dịch vụ được quản lý chứ không phải là điều mà đại lý phải suy nghĩ về.

H: Các mô hình nào hoạt động với smolagents?

Bất kỳ nhà cung cấp nào mà thư viện hỗ trợ. InferenceClientModel bao gồm các mô hình được phục vụ thông qua các nhà cung cấp suy diễn của Hugging Face, và thư viện cũng cung cấp OpenAIModel, AzureOpenAIModel, AmazonBedrockModel, LiteLLMModel, và các backend cục bộ như TransformersModel — xem tài liệu tham khảo mô hình smolagents để biết danh sách hiện tại. Phía MCP không phân biệt mô hình: các công cụ trông giống hệt nhau bất kể mô hình nào suy diễn qua chúng.

H: Việc thu thập dữ liệu bằng một đại lý AI có hợp pháp không?

Cùng một quy tắc áp dụng như đối với bất kỳ trình thu thập nào: chỉ thu thập các trang công khai, tôn trọng điều khoản và chỉ dẫn robot của trang mục tiêu, giữ khối lượng giới hạn, và xử lý bất kỳ dữ liệu cá nhân nào theo luật về quyền riêng tư áp dụng cho bạn. Một đại lý thay đổi cách thức thu thập diễn ra, không phải những gì bạn được phép thu thập — khi có nghi ngờ, hãy hỏi cố vấn trước khi bạn mở rộng khối lượng công việc.