DSPy + Scrapeless: Cung cấp cho chương trình DSPy của bạn các công cụ web trực tiếp qua MCP.

Tóm tắt:

• DSPy chuyển đổi các công cụ của Scrapeless MCP Server thành các đối tượng dspy.Tool với dspy.Tool.from_mcp_tool, cung cấp cho một chương trình DSPy tất cả 21 công cụ web, từ scrape_markdown đến bộ trình duyệt đầy đủ.
• Mỗi công cụ được chuyển đổi đều gắn liền với một mcp.ClientSession đang hoạt động, vì vậy các công cụ chỉ hoạt động khi phiên đó đang mở; giữ toàn bộ luồng bên trong một khối async with ClientSession(...).
• Việc chuyển đổi các công cụ và gọi một công cụ trực tiếp bằng acall không yêu cầu cấu hình mô hình ngôn ngữ; chỉ có việc chạy dspy.ReAct cần có một mô hình ngôn ngữ.
• dspy.Tool.from_mcp_tool(session, tool) nhận phiên và một công cụ MCP và trả về một công cụ DSPy mà bạn có thể gọi hoặc chuyển cho một module.
• Một cuộc gọi trực tiếp scrape_markdown trả về trang dưới dạng Markdown, sẵn sàng để đưa vào chữ ký DSPy.
• Bắt đầu trên gói miễn phí Scrapeless và cung cấp cho chương trình DSPy của bạn những công cụ web thực sự.

DSPy được xây dựng dựa trên một ý tưởng khác với hầu hết các khung tác nhân: bạn khai báo những gì bạn muốn với một chữ ký và để DSPy xử lý việc nhắc nhở. Các công cụ phù hợp với mô hình đó một cách rõ ràng, nhưng DSPy không cung cấp cách để truy cập internet live. Giao thức Model Context cung cấp điều đó. Chuyển đổi các công cụ của một máy chủ MCP thành các công cụ DSPy và một module dspy.ReAct có thể gọi chúng theo cách tương tự như nó gọi bất kỳ công cụ nào khác.

Hướng dẫn này kết nối DSPy với Scrapeless MCP Server, chuyển đổi 21 công cụ của nó, gọi một công cụ trên thực tế và chỉ ra nơi cần có một khóa mô hình ngôn ngữ. Việc chuyển đổi và cuộc gọi trực tiếp được xác thực với máy chủ live; việc chạy module được đánh dấu là một yêu cầu tiên quyết mà nó cần.

Tại sao Scrapeless MCP

Scrapeless MCP Server cung cấp các công cụ web-scraping và trình duyệt mà một tác nhân có thể gọi trực tiếp, vì vậy lớp scraping không phải là thứ bạn xây dựng hoặc lưu trữ. Một kết nối phục vụ 21 công cụ: scrape_markdown và scrape_html cho nội dung, google_search và google_trends cho dữ liệu tìm kiếm, scrape_screenshot cho các bản chụp, và một bộ browser_* hoàn chỉnh điều khiển một trình duyệt cloud. DSPy kết nối với tất cả chúng thông qua dspy.Tool.from_mcp_tool, chuyển đổi mỗi công cụ MCP thành công cụ DSPy gốc.

Các công cụ browser_* điều khiển trình duyệt cloud Scrapeless, vì vậy một chương trình có thể điều hướng một trang tương tác và đọc những gì được hiển thị, tất cả trên cơ sở hạ tầng của Scrapeless. Đối với cái nhìn giao thức của cùng một máy chủ, hướng dẫn tích hợp MCP sẽ đề cập đến cách các khách hàng MCP kết nối tổng quát.

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

• Python 3.10 trở lên.
• Một khóa API Scrapeless từ bảng điều khiển, được xuất dưới dạng SCRAPELESS_API_KEY.
• Một khóa mô hình ngôn ngữ (như OPENAI_API_KEY) chỉ dành cho việc chạy dspy.ReAct. Việc chuyển đổi và gọi các công cụ không cần một cái.

Cài đặt

Cài đặt DSPy và thư viện khách MCP.

pip install dspy mcp

Đặt khóa Scrapeless của bạn trong shell. Sử dụng khóa thực tại thời gian chạy và giữ chỗ từ mã nguồn của bạn.

export SCRAPELESS_API_KEY="sk_your_key_here"

Mở một Phiên và Chuyển đổi các Công cụ

Cầu nối MCP của DSPy hoạt động trên một phiên đang hoạt động. Mở một kết nối HTTP có thể stream, bọc nó trong một mcp.ClientSession, khởi tạo, liệt kê các công cụ của máy chủ và chuyển đổi từng công cụ bằng dspy.Tool.from_mcp_tool. Khóa Scrapeless được gửi trong tiêu đề x-api-token.

import asyncio
import os

import dspy
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client


async def main() -> None:
    async with streamablehttp_client(
        "https://api.scrapeless.com/mcp", headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            mcp_tools = (await session.list_tools()).tools
            tools = [dspy.Tool.from_mcp_tool(session, t) for t in mcp_tools]
            names = sorted(t.name for t in tools)
            print("Công cụ dspy:", len(tools))
            print("các công cụ:", ", ".join(names))


asyncio.run(main())

Máy chủ live trả về 21 công cụ DSPy, được chuyển đổi mà không cần cấu hình mô hình ngôn ngữ.

Công cụ dspy: 21
các công cụ: browser_click, browser_close, browser_create, browser_get_html, browser_get_text, browser_go_back, browser_go_forward, browser_goto, browser_press_key, browser_screenshot, browser_scroll, browser_scroll_to, browser_snapshot, browser_type, browser_wait, browser_wait_for, google_search, google_trends, scrape_html, scrape_markdown, scrape_screenshot

Mỗi công cụ đã chuyển đổi giữ một tham chiếu đến session, đó là lý do tại sao quá trình chuyển đổi và mọi thứ sử dụng các công cụ đều nằm trong khối async with ClientSession(...). Đóng phiên làm cho các công cụ ngừng hoạt động. Lớp vận chuyển và lớp thông điệp tuân theo đặc tả Model Context Protocol, dựa trên đặc tả JSON-RPC 2.0.

Gọi một Công Cụ

Một công cụ DSPy có thể được gọi độc lập, vì vậy bạn có thể chạy một cái trước khi xây dựng một mô-đun. acall gọi công cụ với các tham số từ khóa và trả về kết quả của nó.

import asyncio
import os

import dspy
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client


async def main() -> None:
    async with streamablehttp_client(
        "https://api.scrapeless.com/mcp", headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            mcp_tools = (await session.list_tools()).tools
            tools = [dspy.Tool.from_mcp_tool(session, t) for t in mcp_tools]
            scrape_markdown = next(t for t in tools if t.name == "scrape_markdown")
            result = await scrape_markdown.acall(url="https://quotes.toscrape.com/")
            text = result if isinstance(result, str) else str(result)
            print("số ký tự markdown:", len(text))
            print("chứa một câu trích dẫn:", "Thế giới mà chúng ta đã tạo ra" in text)


asyncio.run(main())

Lời gọi trả về trang dưới dạng Markdown, và kiểm tra nội dung xác nhận rằng một câu trích dẫn thực sự có mặt.

số ký tự markdown: 4308
chứa một câu trích dẫn: True

Gọi một công cụ trực tiếp là cách nhanh nhất để xác nhận kết nối và kiểm tra những gì một công cụ trả về, và nó là cùng một đối tượng mà một mô-đun sẽ gọi. Tài liệu DSPy bao gồm đầy đủ các công cụ, chữ ký và mô-đun.

Kết Nối Các Công Cụ Vào Một Mô-Đun

dspy.ReAct nhận một chữ ký và một danh sách các công cụ và chạy vòng lặp lý do-hành động. Đây là bước cần một mô hình ngôn ngữ: cấu hình một cái với dspy.configure, sau đó để mô-đun quyết định khi nào gọi scrape_markdown hoặc công cụ khác. Bởi vì các công cụ được liên kết với phiên, mô-đun chạy bên trong cùng một khối async with ClientSession(...) mà đã chuyển đổi chúng.

Lưu ý: dspy.configure(lm=...) và việc chạy dspy.ReAct cần một khóa mô hình ngôn ngữ như OPENAI_API_KEY, điều này không được thiết lập ở đây. Việc chuyển đổi 21 công cụ và lời gọi scrape_markdown trực tiếp ở trên chạy mà không cần nó. Khối này được hiển thị với hình dạng chính xác của nó; chỉ có việc đi vòng quanh mô hình là một khoảng trống yêu cầu.

# bên trong khối `async with ClientSession(...)`, sau khi chuyển đổi `tools`
dspy.configure(lm=dspy.LM("openai/gpt-4o"))
agent = dspy.ReAct("câu hỏi -> câu trả lời", tools=tools)
result = await agent.acall(
    question="Lấy https://quotes.toscrape.com/ và liệt kê ba câu trích dẫn đầu tiên cùng với tác giả của chúng."
)
print(result.answer)

Tại thời điểm chạy, mô-đun đọc chữ ký, gọi scrape_markdown để lấy trang, lý luận về Markdown mà lời gọi trực tiếp đã chứng minh, và điền vào trường answer. Các công cụ là cùng một đối tượng dù cho mô-đun gọi chúng hay bạn thực hiện.

Kết Luận

DSPy cộng với Máy chủ MCP Scrapeless giữ phong cách tuyên bố của DSPy trong khi thêm khả năng truy cập web thực sự. dspy.Tool.from_mcp_tool chuyển đổi 21 công cụ, acall chứng minh một công cụ hoạt động, và dspy.ReAct biến chúng thành một chương trình chạy. Một quy tắc cần nhớ là các công cụ sống dựa trên phiên, vì vậy hãy duy trì dòng chảy trong một khối phiên duy nhất, và chỉ việc chạy mô-đun cần một khóa mô hình. Bắt đầu từ các kịch bản ở trên, xác định phạm vi các công cụ theo những gì chữ ký của bạn cần, và để DSPy thực hiện việc nhắc nhở.

Tạo một tài khoản Scrapeless miễn phí để nhận một khóa API, và kiểm tra giá cả Scrapeless khi bạn lập kế hoạch cho một chương trình định kỳ.

Câu Hỏi Thường Gặp

Q: DSPy có cần một mô hình ngôn ngữ để tải các công cụ MCP không?

Không. Mở phiên, liệt kê các công cụ, chuyển đổi chúng với dspy.Tool.from_mcp_tool, và gọi một cái với acall tất cả đều hoạt động chỉ với khóa API Scrapeless. Một khóa mô hình ngôn ngữ chỉ cần cho dspy.ReAct, khi mà mô-đun tự quyết định công cụ nào sẽ gọi.

Q: Tại sao mã phải ở trong một khối ClientSession?

dspy.Tool.from_mcp_tool liên kết mỗi công cụ với mcp.ClientSession mà bạn truyền vào, vì vậy các công cụ thực hiện các cuộc gọi qua phiên đó. Khi khối async with ClientSession(...) thoát, phiên đóng lại và các công cụ không còn hoạt động được nữa, đó là lý do tại sao việc chuyển đổi và sử dụng các công cụ phải nằm trong cùng một khối.
Hỏi: Tích hợp MCP của DSPy khác với các khung adapter như thế nào?

DSPy chuyển đổi các công cụ từ một mcp.ClientSession thô với dspy.Tool.from_mcp_tool, thay vì thông qua một adapter cấp cao hơn quản lý kết nối cho bạn. Đánh đổi là có quyền kiểm soát rõ ràng về tuổi thọ của phiên giao dịch để đổi lấy một phụ thuộc ít hơn, và nó giữ các công cụ dưới dạng các đối tượng dspy.Tool thông thường.

Hỏi: Làm thế nào để tôi gọi một công cụ mà không cần xây dựng một mô-đun?

Mỗi công cụ đã chuyển đổi đều có thể được gọi bằng acall và các đối số từ khóa, vì vậy await scrape_markdown.acall(url="...") trả về kết quả của công cụ ngay lập tức. Điều này hữu ích để xác nhận kết nối và kiểm tra đầu ra trước khi bạn gói các công cụ vào một mô-đun dspy.ReAct.

Hỏi: Làm thế nào để tôi cung cấp cho một mô-đun chỉ một số công cụ?

from_mcp_tool chạy cho từng công cụ, vì vậy hãy xây dựng danh sách tools chỉ từ các công cụ MCP mà bạn muốn, hoặc lọc danh sách đã chuyển đổi trước khi truyền nó cho dspy.ReAct. Cung cấp cho một mô-đun chỉ scrape_markdown và google_search thì an toàn hơn so với toàn bộ bộ 21 công cụ khi nhiệm vụ chỉ cần nội dung và tìm kiếm.

Hỏi: Việc thu thập thông tin qua các công cụ có bị ràng buộc bởi các quy tắc của mục tiêu không?

Có. Các công cụ truy xuất các trang công cộng, và bạn vẫn có trách nhiệm tuân thủ các điều khoản của mỗi mục tiêu và các chỉ dẫn trong Giao thức loại trừ Robots. Giữ cho khối lượng hạn chế và dữ liệu công khai, và định hình mô-đun theo các công cụ mà nhiệm vụ thực sự cần.