LlamaIndex + Scrapeless: Cung cấp cho chỉ mục của bạn các trang web trực tiếp

Một chỉ mục truy xuất chỉ cập nhật như các tài liệu mà bạn đưa vào nó. LlamaIndex xử lý việc chia khối, nhúng và truy xuất tốt; phần bị hỏng một cách im lặng là bước trước tất cả những điều đó, nơi mà các trang web trực tiếp phải trở thành văn bản sạch.

Kết nối LlamaIndex với Máy chủ MCP Scrapeless bao gồm bước đó. Các công cụ MCP trả về các trang đã được hiển thị dưới dạng markdown, LlamaIndex bao bọc chúng thành các đối tượng Document, và phần còn lại của quy trình đưa vào của bạn tiếp tục không thay đổi. Hướng dẫn này thực hiện kết nối, tìm kiếm công cụ, fetch một trang thực sự, và chia tài liệu thành nút từ đầu đến cuối.

Điều gì mà thiết lập này mang lại cho chỉ mục của bạn

Mã đưa vào của bạn có 21 công cụ gọi được từ một kết nối, và chúng đến dưới dạng công cụ LlamaIndex gốc thay vì điều gì đó mà bạn phải tự bao bọc.

Các nhóm quan trọng cho việc đưa vào:

• Truy xuất trang — scrape_markdown trả về một trang đã được chuyển đổi thành markdown, đây là định dạng mà cả bộ chia và mô hình nhúng đều xử lý tốt nhất. scrape_html và scrape_screenshot trả về hai hình thức còn lại.
• Tìm kiếm — google_search và google_trends cho phép một công việc đưa vào phát hiện các URL thay vì được đưa một danh sách cố định.
• Kiểm soát trình duyệt trực tiếp — mười sáu công cụ browser_* cho các trang cần tương tác trước khi nội dung xuất hiện.

Việc hiển thị, định tuyến proxy và xử lý truy cập đều diễn ra phía máy chủ, vì vậy quy trình đưa vào vẫn là một công việc Python đơn giản mà không cần cài trình duyệt.

Tại sao Máy chủ MCP Scrapeless

Thông số kỹ thuật của Giao thức Ngữ cảnh Mô hình định nghĩa cách một khách hàng phát hiện công cụ và các sơ đồ tham số của chúng từ một máy chủ, điều này làm cho nó khác biệt so với việc viết một trình hỗ trợ fetch: danh sách công cụ và các tham số của từng công cụ đến từ máy chủ thay vì được mã cứng trong dự án của bạn. Các cuộc gọi được thực hiện dưới dạng tin nhắn JSON-RPC 2.0.

Scrapeless lưu trữ điểm cuối, vì vậy không có quy trình máy chủ nào chạy song song với bộ chỉ mục của bạn. Xác thực chỉ là một tiêu đề. Nhóm browser_* được hỗ trợ bởi Trình duyệt Thu thập dữ liệu Scrapeless, và các tham số cho từng công cụ được tài liệu trong tài liệu của Scrapeless.

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

• Python 3.10 hoặc mới hơn. Cả hai llama-index-core và llama-index-tools-mcp hiện tại đều yêu cầu >=3.10,<4.0.
• Một khóa API Scrapeless từ bảng điều khiển.
• Chỉ cho phần tác nhân: một gói tích hợp LLM như llama-index-llms-openai cộng với khóa của nhà cung cấp đó.

Lưu ý: Mọi thứ qua phần đưa vào dưới đây được thực hiện với một khóa Scrapeless và không có khóa nhà cung cấp mô hình. Kết nối MCP, phát hiện công cụ, sơ đồ tham số, cuộc gọi công cụ trực tiếp, và việc chia Document thành nút đều đã chạy. Bước tác nhân ở cuối là một khoảng cách điều kiện tiên quyết — việc xây dựng một FunctionAgent gây ra ImportError: không tìm thấy gói llama-index-llms-openai nếu không có một tích hợp LLM được cài đặt, vì vậy khối đó được hiển thị là mã bạn thêm vào thay vì là đầu ra đã được ghi lại.

Cài đặt

pip install "llama-index-tools-mcp==0.4.8"

Gói đó mang theo llama-index-core và khách hàng mcp. Thiết lập khóa trong shell của bạn:

export SCRAPELESS_API_KEY="your_api_key_here"

Kết nối và Liệt kê các Công cụ

BasicMCPClient nhận URL điểm cuối và các tiêu đề; McpToolSpec chuyển đổi danh sách công cụ của máy chủ thành các công cụ LlamaIndex:

import asyncio, os
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

async def main():
    client = BasicMCPClient(
        "https://api.scrapeless.com/mcp",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    )
    spec = McpToolSpec(client=client)
    tools = await spec.to_tool_list_async()
    print("số công cụ:", len(tools))
    print("tên mẫu:", sorted(t.metadata.name for t in tools)[:6])

asyncio.run(main())

số công cụ: 21
tên mẫu: ['browser_click', 'browser_close', 'browser_create', 'browser_get_html', 'browser_get_text', 'browser_go_back']

API là bất đồng bộ trong suốt, đó là lý do tại sao ví dụ chạy bên trong asyncio.run. Tên công cụ đến theo dạng phẳng, không có tiền tố máy chủ hoặc không gian tên chấm, vì vậy scrape_markdown là tên thực mà mã của bạn và tác nhân của bạn sẽ sử dụng.

Chỉ lấy những công cụ cần thiết cho công việc

Một công việc đưa vào hiếm khi cần kiểm soát phiên trình duyệt. McpToolSpec chấp nhận allowed_tools và chỉ trả về những công cụ đó, điều này giữ cho bề mặt nhỏ và các sơ đồ dễ đọc:

import asyncio, os
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

async def main():
    client = BasicMCPClient(
        "https://api.scrapeless.com/mcp",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    )

spec = McpToolSpec(client=client, allowed_tools=["scrape_markdown"])
tools = await spec.to_tool_list_async()

tool = tools[0]
print("số lượng đã lọc:", len(tools))
print("tên:", tool.metadata.name)
print("trường fn_schema:", list(tool.metadata.fn_schema.model_fields))

asyncio.run(main())

```text
số lượng đã lọc: 1
tên: scrape_markdown
trường fn_schema: ['url']

Lược đồ đến từ server, vì vậy nó là hợp đồng thực sự thay vì một giả định: scrape_markdown nhận một url duy nhất. LlamaIndex xuất hiện nó dưới dạng fn_schema, mô hình Pydantic mà một agent sẽ sử dụng để xây dựng cuộc gọi của nó.

Bạn đã sẵn sàng để chỉ vào các nguồn của riêng bạn chưa? Tạo một tài khoản miễn phí Scrapeless và kết nối với khóa từ bảng điều khiển của bạn.

Chuyển Trang Trực Tiếp Thành Các Node

Đây là phần quan trọng cho việc truy xuất. Gọi công cụ trực tiếp, bọc từng kết quả như một Document với nguồn trong metadata, sau đó chia thành các node:

import asyncio, os
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
from llama_index.core import Document
from llama_index.core.node_parser import SentenceSplitter

async def main():
    client = BasicMCPClient(
        "https://api.scrapeless.com/mcp",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    )
    spec = McpToolSpec(client=client, allowed_tools=["scrape_markdown"])
    tool = (await spec.to_tool_list_async())[0]

    urls = [
        "https://quotes.toscrape.com/js/",
        "https://quotes.toscrape.com/page/2/",
    ]

    docs = []
    for url in urls:
        markdown = str(await tool.acall(url=url))
        docs.append(Document(text=markdown, metadata={"source": url}))
    print(f"tài liệu: {len(docs)}")

    splitter = SentenceSplitter(chunk_size=256, chunk_overlap=32)
    nodes = splitter.get_nodes_from_documents(docs)
    print(f"node sau khi chia: {len(nodes)}")
    print(f"nguồn của node đầu tiên: {nodes[0].metadata['source']}")
    print(f"số ký tự của node đầu tiên: {len(nodes[0].get_content())}")

asyncio.run(main())

tài liệu: 2
node sau khi chia: 14
nguồn của node đầu tiên: https://quotes.toscrape.com/js/
số ký tự của node đầu tiên: 571

Nhiều điều trong đầu ra đó đáng để đọc một cách cẩn thận.

URL đầu tiên là một trang được client render — nội dung của nó được viết vào DOM bởi một script — và nó vẫn tạo ra markdown sử dụng được, vì render xảy ra ở phía server trước khi chuyển đổi. Một truy vấn HTTP thuần túy đến cùng URL đó sẽ trả về markup mà không có nội dung nào trong đó.

chunk_size=256 đếm tokens, không phải ký tự, đó là lý do tại sao node đầu tiên dài 571 ký tự. Điều chỉnh một splitter theo ký tự là cách phổ biến để kết thúc với các chunk tràn ra ngữ cảnh của mô hình nhúng.

metadata={"source": url} trên mỗi Document vẫn tồn tại sau khi chia và gắn lên mỗi node được tạo ra từ nó. Đó là điều cho phép một kết quả truy xuất trích dẫn nguồn gốc của nó, và dễ dàng hơn nhiều để gắn ở đây hơn là tái tạo sau này.

Markdown là định dạng trung gian phù hợp cho điều này: tiêu đề và liên kết được giữ lại, trong khi script, phong cách, và markup bố cục không có, vì vậy ngân sách nhúng được sử dụng cho nội dung.

Cung Cấp Các Công Cụ Cho Một Agent

Khi các công cụ đã có trong tay, một agent có thể quyết định cái nào để gọi thay vì theo một danh sách URL cố định. Bước này cần một gói tích hợp LLM và khóa của nhà cung cấp đó.

Lưu ý: Khối này là một lỗ hổng tiền yêu cầu. Nếu không có tích hợp LLM được cài đặt, việc xây dựng agent gây ra ImportError: llama-index-llms-openai package not found, please run pip install llama-index-llms-openai, vì vậy không có đầu ra nào được hiển thị cho nó.

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

agent = FunctionAgent(
    tools=tools,
    llm=OpenAI(model="gpt-4.1-mini"),
    system_prompt="Nghiên cứu các trang công cộng và trả lại ghi chú sạch sẽ kèm nguồn.",
)

response = await agent.run("Tóm tắt các tác giả được trích dẫn trên quotes.toscrape.com")
print(response)

Kết Luận

Kết nối LlamaIndex với Máy Chủ MCP Scrapeless cần một client, một đặc tả công cụ, và một header. Server cung cấp 21 công cụ với các lược đồ đối số riêng của chúng, allowed_tools thu hẹp chúng đến những gì công việc nhập liệu thực sự cần, và scrape_markdown trả về các trang ở định dạng mà cả một splitter và mô hình nhúng đều ưa thích.

Thói quen đáng để mang theo là gắn URL nguồn dưới dạng metadata Document lúc lấy dữ liệu. Nó chỉ mất một từ điển, nó vẫn tồn tại sau khi chia node, và đó là điều biến một hit truy xuất thành câu trả lời mà bạn có thể theo dõi lại đến một trang.
Bắt đầu với gói miễn phí Scrapeless để nhận một khóa, kiểm tra giá Scrapeless khi bạn định kích thước một lần nạp dữ liệu, và xem tổng quan về máy chủ MCP Scrapeless để tham khảo đầy đủ công cụ.

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

H: Điểm cuối của máy chủ MCP Scrapeless cho LlamaIndex là gì?

Điểm cuối được lưu trữ là https://api.scrapeless.com/mcp, được truy cập với khóa của bạn trong tiêu đề x-api-token thông qua BasicMCPClient. Không có quy trình máy chủ cục bộ nào cần chạy, vì các công cụ được phục vụ từ xa.

H: Có bao nhiêu công cụ mà máy chủ MCP Scrapeless cung cấp cho LlamaIndex?

Một kết nối trực tiếp trả về 21: mười sáu công cụ kiểm soát phiên browser_*, ba công cụ lấy trang (scrape_markdown, scrape_html, scrape_screenshot), và hai công cụ tìm kiếm (google_search, google_trends). Hãy liệt kê chúng tại thời điểm chạy thay vì giả định, vì một máy chủ có thể thêm công cụ giữa các bản phát hành.

H: Tôi có thể chỉ tải một số công cụ MCP không?

Có. Truyền allowed_tools=["scrape_markdown"] cho McpToolSpec và danh sách sẽ chỉ trở về với công cụ đó. Đối với việc nạp dữ liệu, điều này là đáng làm — nó giữ cho các sơ đồ dễ đọc và ngăn một tác nhân mở các phiên duyệt mà nó không cần.

H: Tôi có cần một khóa LLM để lấy trang qua MCP không?

Không. Kết nối, phát hiện công cụ, kiểm tra sơ đồ, và gọi trực tiếp tool.acall(...) đều hoạt động chỉ với khóa Scrapeless. Một nhà cung cấp mô hình là cần thiết khi bạn giao các công cụ cho một tác nhân, vì đó là khi cần quyết định công cụ nào sẽ gọi.

H: Tại sao nên sử dụng markdown thay vì HTML để lấy dữ liệu?

Markdown giữ cấu trúc giúp việc lấy dữ liệu — tiêu đề, danh sách, liên kết — và loại bỏ các script, kiểu dáng, và markup bố cục chiếm dụng bối cảnh nhúng mà không thêm ý nghĩa. scrape_html vẫn là lựa chọn đúng khi bạn định chạy các bộ chọn riêng của mình thay vì nhúng văn bản.

H: Làm thế nào tôi theo dõi được khối dữ liệu lấy được đến từ trang nào?

Đặt URL vào Document(metadata={"source": url}) khi bạn tạo tài liệu. Metadata đó sẽ được sao chép vào mỗi nút mà bộ chia tạo ra từ nó, vì vậy mỗi khối dữ liệu lấy được mang theo nguồn gốc của nó mà không cần quản lý bổ sung.

H: Tôi nên kiểm tra gì trước khi nạp dữ liệu một trang web?

Xem xét các điều khoản của trang web và các chỉ thị trong /robots.txt, tuân theo tiêu chuẩn Giao thức loại trừ Robot. Giới hạn việc nạp dữ liệu cho các trang công khai, làm việc từ một danh sách URL rõ ràng hoặc một bước khám phá giới hạn, và ghi lại URL nguồn trên mỗi tài liệu để nguồn gốc của bất kỳ thứ gì chỉ số trả về vẫn rõ ràng.