Cách kết nối Scrapeless với ChatGPT bằng hành động GPT tùy chỉnh

TL;DR:

• ChatGPT không thể lấy một máy chủ API-key MCP làm kết nối. Chế độ nhà phát triển MCP chấp nhận OAuth 2.1 hoặc không xác thực, và tài liệu của OpenAI nói rằng ChatGPT "không thể trình bày các khóa API tùy chỉnh".
• Đường dẫn hoạt động là một Hành động GPT tùy chỉnh: một sơ đồ OpenAPI cộng với xác thực API-key trên tiêu đề tùy chỉnh.
• Tiêu đề là x-api-token, không phải Authorization: Bearer. Đặt loại xác thực thành API Key, sau đó là Tùy chỉnh, sau đó là tên tiêu đề đó.
• Yêu cầu Markdown, không phải HTML. Trang này có 8,676 ký tự dưới dạng Markdown so với 50,403 ký tự dưới dạng HTML — cắt giảm 83% trong bối cảnh mà mô hình dành cho markup.
• response_type chỉ thực hiện nó cùng js_render: true. Bỏ js_render ra và yêu cầu giống nhau trả về 50,368 ký tự HTML với HTTP 200. outputFormat được chấp nhận và bị bỏ qua trong im lặng, trả về đầy đủ 50,403 ký tự HTML.
• Sơ đồ bên dưới vượt qua openapi-spec-validator theo OpenAPI 3.1.0, và yêu cầu mà nó mô tả đã được thực hiện trực tiếp: {code: 200, data: string}.
• Lấy khóa trên kế hoạch miễn phí Scrapeless trước khi bạn bắt đầu.

Hỏi ChatGPT về một trang mà nó chưa thấy và bạn sẽ nhận được một tóm tắt về dữ liệu đào tạo của nó hoặc một kết quả duyệt mà bạn không thể kiểm soát. Một Hành động thay đổi cấu trúc: bạn cung cấp cho mô hình một thao tác HTTP mà nó có thể gọi, với các tham số bạn đã định nghĩa, đối với một API bạn đã chọn.

Điều đầu tiên cần làm rõ là cơ chế nào mà ChatGPT thực sự chấp nhận, vì câu trả lời rõ ràng là sai.

Tại Sao Đây Là Một Hành Động Và Không Phải Là Kết Nối MCP

Mọi khách hàng lớn khác đều lấy máy chủ Scrapeless MCP làm một kết nối HTTP từ xa với khóa trên một tiêu đề. ChatGPT không làm như vậy, và điều đó đáng để xem xét trước khi xây dựng xung quanh nó.

Điểm cuối yêu cầu một tiêu đề cố định. Gọi mà không có một tiêu đề nào:

POST https://api.scrapeless.com/mcp   (no auth)
-> HTTP 401
   body: Unauthorized: Missing x-api-token header
   www-authenticate: None

Tiêu đề www-authenticate bị thiếu là điều quan trọng. Dưới khung xác thực HTTP một 401 là nơi mà một máy chủ quảng bá cách xác thực, và một khách hàng tìm kiếm một thử thách OAuth không tìm thấy gì để theo dõi. Cũng không có siêu dữ liệu OAuth nào để khám phá:

/.well-known/oauth-protected-resource       404
/.well-known/oauth-authorization-server     404
/.well-known/oauth-protected-resource/mcp   404

đặc tả Giao thức Ngữ cảnh Mô hình cho phép cả hai sắp xếp — một mã thông báo trần trên một tiêu đề là một triển khai MCP hoàn toàn bình thường. Rào cản nằm ở phía ChatGPT: các kết nối chế độ nhà phát triển của nó hỗ trợ OAuth 2.1 hoặc không có xác thực, và tài liệu của OpenAI nêu rõ rằng ChatGPT không thể trình bày các khóa API tùy chỉnh.

Vì vậy, không có URL nào để dán. Đường dẫn được hỗ trợ cho một API HTTP có khóa là một Hành động GPT, điều này hỗ trợ xác thực API-key với tên tiêu đề mà bạn chọn.

Điều Kiện Tiên Quyết

• Một kế hoạch ChatGPT bao gồm việc tạo ra GPTs.
• Một khóa API Scrapeless.
• Không có hosting, không có proxy, không có quy trình địa phương. Hành động gọi api.scrapeless.com trực tiếp.

Bước 1: Sơ Đồ OpenAPI

Một Hành động là một tài liệu OpenAPI mô tả một hoặc nhiều thao tác. Cái này mô tả một thao tác duy nhất: lấy một trang đã được render và trả về nó dưới dạng Markdown.

openapi: 3.1.0
info:
  title: Scrapeless Universal Scraping API
  description: Fetch a fully rendered web page and return it as Markdown or HTML.
  version: "1.0.0"
servers:
  - url: https://api.scrapeless.com
paths:
  /api/v2/unlocker/request:
    post:
      operationId: scrapeWebPage
      summary: Fetch a web page with JavaScript rendering and return it as Markdown
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [actor, input]
              properties:
                actor:
                  type: string
                  enum: [unlocker.webunlocker]
                  description: The Scrapeless actor to run.
                input:
                  type: object
                  required: [url, js_render, response_type]
                  properties:
                    url:
                      type: string
                      format: uri
                      description: The page to fetch.
                    js_render:
                      type: boolean
                      enum: [true]
                      default: true
                      description: Must be true. response_type only takes effect when JavaScript rendering is on.
                    response_type:
                      type: string
                      enum: [markdown, html]
                      default: markdown
                      description: Return the page as Markdown or raw HTML.
      responses:
        "200":
          description: The rendered page.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  data:
                    type: string
                    description: The rendered page, as Markdown or HTML.
        "401":
          description: Missing or invalid API token.
components:
  securitySchemes:
    scrapelessApiKey:
      type: apiKey
      in: header
      name: x-api-token
security:
  - scrapelessApiKey: []

Ba sự chọn lựa có chủ ý ở đó.

actor là một enum với một giá trị thay vì một chuỗi tự do. Một mô hình được cho một trường văn bản tự do sẽ cuối cùng phát minh ra một tên diễn viên; một enum làm cho giá trị hợp lệ duy nhất là tùy chọn duy nhất.

operationId là scrapeWebPage, và đó là tên bạn tham chiếu trong hướng dẫn của GPT. Một id mập mờ sẽ sản xuất lựa chọn công cụ mập mờ.

response_type mặc định thành markdown, vì lý do trong bước 3, và cả nó và js_render đều được liệt kê là bắt buộc. Một mặc định sơ đồ là tài liệu: nó không bắt mô hình gửi trường, và mặc định của chính API cho js_render là tắt.

Việc xác thực trước khi dán là đáng giá trong ba mươi giây — đặc tả OpenAPI 3.1.0 rất nghiêm ngặt về cấu trúc, và thông báo lỗi của bộ tạo thì ngắn gọn:

pip install openapi-spec-validator

python3 -c "
from openapi_spec_validator import validate
from openapi_spec_validator.readers import read_from_filename
spec, _ = read_from_filename('scrapeless-action.yaml')
validate(spec)
print('valid')"

valid

Bước 2: Xác Thực

Trong bộ tạo GPT, mở bảng xác thực của Hành động và đặt:

Mặc định dưới API Key là Bearer, gửi Authorization: Bearer <key>. Scrapeless đọc x-api-token và không gì khác, vì vậy việc để mặc định sẽ tạo ra một 401 mà bộ tạo chỉ hiển thị khi Hành động được gọi lần đầu — sau khi sơ đồ đã được xác thực.

Lưu ý: trình xây dựng là một giao diện web, vì vậy bước này không được thực hiện như một phần của việc xác minh cho bài viết này. Mọi tuyên bố về API — sơ đồ, tên tiêu đề, hình dạng phản hồi và kích thước bên dưới — đến từ các cuộc gọi trực tiếp chống lại api.scrapeless.com.

Bước 3: Yêu cầu Markdown

Một cài đặt này quyết định mức độ bối cảnh mà bộ kết nối sử dụng trước khi nó đọc bất cứ điều gì, và sự khác biệt là có thể đo được.

Trang danh mục cùng một, lấy hai lần:

response_type=markdown      8,676 chars
default (html)             50,403 chars

Markdown nhỏ hơn 83%. Phản hồi của hành động GPT đi vào bối cảnh của mô hình, vì vậy việc trả về HTML chi tiêu hầu hết ngân sách đó cho các thẻ, tập lệnh nội tuyến và thuộc tính mà mô hình sẽ bỏ qua.

Có một cái bẫy bên cạnh. outputFormat trông có vẻ như nó nên hoạt động và được chấp nhận mà không phàn nàn:

input.response_type = "markdown"   ->  8,676 chars  (markdown)
input.outputFormat  = "markdown"   -> 50,403 chars  (HTML)

Cuộc gọi thứ hai thành công, trả về HTTP 200, và âm thầm trả lại HTML vì outputFormat không phải là một tham số mà diễn viên đọc. Một khóa không xác định bị bỏ qua thay vì bị từ chối là loại lỗi khó khăn hơn — không có gì bị lỗi, đầu ra chỉ bị sai hình dạng và gần sáu lần lớn hơn so với ngân sách bạn đã dự tính.

Cái bẫy thứ hai thì yên tĩnh hơn. response_type chỉ có hiệu lực khi kết xuất JavaScript đang bật, và mặc định của API là tắt. Gửi response_type: "markdown" mà không có js_render: true và cuộc gọi trả về HTTP 200 với 50,368 ký tự HTML, không có lỗi và không có cảnh báo. Sơ đồ ở trên gán js_render cho true và liệt kê nó là bắt buộc vì chính lý do này, và hướng dẫn bên dưới tên cả hai trường.

Xây dựng điều này ngay bây giờ? Kế hoạch miễn phí Scrapeless bao gồm đủ yêu cầu để kiểm tra hành động từ đầu đến cuối.

Bước 4: Hướng dẫn Gọi Nó

Sơ đồ cung cấp cho mô hình một khả năng; hướng dẫn quyết định khi nào nó sẽ sử dụng nó. Đặt tên cho hoạt động một cách rõ ràng:

When the user gives you a URL, or asks about the current contents of a
specific page, call scrapeWebPage with that URL, js_render true and
response_type "markdown". Do not answer from memory when a URL is present.

Return what the page says, and quote the exact figures it contains rather
than paraphrasing them. If scrapeWebPage reports a 401, tell the user the
API key is missing or misconfigured and stop.

Đoạn đầu tiên ràng buộc công cụ với một kích hoạt. Nếu không có nó, một mô hình có khả năng duyệt riêng sẽ đôi khi sử dụng điều đó thay vì tạo ra kết quả mà sơ đồ của bạn không có phần.

Những Gì Trở Lại

Bao bì phản hồi là hai trường, và sơ đồ ở trên tuyên bố cả hai:

{
  "code": 200,
  "data": "-   [Home](https://books.toscrape.com/index.html)\n-   [Books](...)\n..."
}

Đã xác minh với API trực tiếp với chính nội dung mà sơ đồ mô tả:

HTTP 200
response keys      : ['code', 'data']
code               : 200 (int)
data               : str, 50403 chars
schema match       : code=integer:True  data=string:True

code là trạng thái riêng của Scrapeless, khác với trạng thái HTTP — cả hai đều là 200 ở đây. data là một chuỗi đơn, đó là lý do tại sao mô hình nhận được một tài liệu thay vì một cấu trúc; nếu bạn muốn các trường, hãy yêu cầu chúng trong hướng dẫn hoặc phân tích chúng tự bạn downstream.

Kết luận

Bộ kết nối là một hoạt động và một tiêu đề. ChatGPT sẽ không nhận một máy chủ MCP với khóa API — đó là giới hạn của nền tảng, được xác nhận bằng một mã 401 mà không có thử thách OAuth, ba mã 404 ở nơi mà siêu dữ liệu sẽ có, và tuyên bố của chính OpenAI — vì vậy cơ chế là một hành động, và cơ chế không phải là phần khó khăn.

Hai lựa chọn quyết định xem nó hoạt động tốt là cả hai đều nhỏ. Đặt tiêu đề tùy chỉnh thành x-api-token, vì mặc định Bearer thất bại vào thời điểm gọi thay vì thiết lập. Và đặt response_type thành markdown cùng với js_render: true, vì 8,676 ký tự Markdown để lại không gian để suy nghĩ trong khi 50,403 ký tự HTML thì không — và vì outputFormat trông có vẻ hợp lý được chấp nhận, bỏ qua, và trả lại cái lớn hơn.

Đối với cùng một API được điều khiển từ mã thay vì từ GPT, hướng dẫn web scraping ChatGPT của chúng tôi bao gồm mẫu mô hình cộng với lấy dữ liệu, trang Universal Scraping API mô tả diễn viên đứng sau hoạt động, tài liệu có tham chiếu toàn bộ tham số, và bảng giá liệt kê mỗi cuộc gọi có giá bao nhiêu.

Sẵn sàng để cho ChatGPT một lần đưa dữ liệu mà bạn kiểm soát? Bắt đầu với kế hoạch miễn phí Scrapeless và dán sơ đồ vào.

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

H: ChatGPT có thể kết nối với máy chủ MCP không?
Có, nhưng chỉ có một cái sử dụng OAuth 2.1 hoặc không xác thực. Các kết nối ở chế độ nhà phát triển không thể trình bày một khóa API tĩnh, điều mà tài liệu của OpenAI nêu rõ. Một máy chủ như điểm cuối Scrapeless MCP, xác thực trên tiêu đề x-api-token và không xuất bản bất kỳ siêu dữ liệu OAuth nào, do đó không thể được thêm vào như một kết nối ChatGPT — một Hành động GPT là con đường hỗ trợ cho nó.

H: Tại sao Hành động GPT của tôi trả về 401?

Thường thì do tên tiêu đề. Loại xác thực Khóa API mặc định là Bearer, gửi Authorization: Bearer <key>; Scrapeless đọc x-api-token. Đặt Loại Xác thực thành Tùy chỉnh và tên tiêu đề thành x-api-token. Lược đồ xác thực theo cả hai cách, vì vậy điều này xuất hiện trong lần gọi đầu tiên thay vì ở giai đoạn thiết lập.

H: Phiên bản OpenAPI nào Hành động GPT cần?

Lược đồ trên là OpenAPI 3.1.0 và xác thực theo đặc tả đó. Giữ tài liệu tối thiểu — một URL máy chủ, giá trị operationId rõ ràng, và không $ref gián tiếp mà bạn không cần — vì bộ phân tích cú pháp của trình xây dựng nghiêm ngặt hơn và các lỗi của nó ít cụ thể hơn so với của một bộ xác thực dành riêng.

H: Làm thế nào để tôi dừng Hành động không làm đầy ngữ cảnh của mô hình?

Trả về Markdown. Đặt response_type thành markdown, với js_render: true trong cùng một yêu cầu, đã giảm trang đó từ 50,403 ký tự xuống 8,676, và phản hồi của Hành động đã tiêu tốn ngân sách ngữ cảnh của cuộc hội thoại. Cũng thu hẹp lược đồ: một hoạt động với một tập tham số nhỏ giúp mô hình có ít không gian hơn để thực hiện một cuộc gọi tốn kém.

H: Tại sao tham số outputFormat của tôi lại không có tác dụng?

Bởi vì nó không phải là tham số mà tác giả đọc. Yêu cầu vẫn trả về HTTP 200 và toàn bộ HTML — 50,403 ký tự thay vì 8,676. Khóa chính xác là response_type, và nó cần js_render: true bên cạnh nó. Các khóa không xác định sẽ bị bỏ qua thay vì bị từ chối ở đây, vì vậy hãy kiểm tra kích thước của những gì quay trở lại khi một cài đặt định dạng dường như không có tác dụng.

H: Một Hành động có thể phơi bày nhiều khả năng Scrapeless hơn không?

Có — thêm một đường dẫn và một operationId cho mỗi hoạt động trong cùng một tài liệu. Giữ mỗi cái chặt chẽ và giữ các hạn chế enum, vì một hoạt động đơn với một trường tác giả tự do mời gọi mô hình đoán. Quyền hạn tối thiểu cũng khiến Hành động dễ dàng hơn để xem xét sau này.

H: Điều này có hoạt động trong một cuộc hội thoại ChatGPT bình thường hay chỉ trong một GPT tùy chỉnh?

Các Hành động thuộc về một GPT mà bạn cấu hình, vì vậy khả năng tồn tại trong GPT đó chứ không phải trong mọi cuộc hội thoại. Bất kỳ ai bạn chia sẻ với nó đều có được hoạt động; việc họ cung cấp khóa riêng của mình phụ thuộc vào cách bạn thiết lập xác thực.