add-provider-package

Tổng quan về kỹ năng add-provider-package

add-provider-package là hướng dẫn triển khai chuyên biệt để tạo một gói @ai-sdk/<provider> mới bên trong vercel/ai. Kỹ năng này phù hợp nhất với maintainer, contributor và các đội ngũ nền tảng API muốn tích hợp một nhà cung cấp model vào AI SDK với đúng cấu trúc package, đúng tầng adapter và đúng quy ước của repository.

add-provider-package thực sự giúp bạn làm gì

Công việc cốt lõi ở đây không phải chỉ là “viết vài lớp wrapper.” add-provider-package giúp bạn thêm một provider package khớp với kiến trúc nội bộ của AI SDK, export đúng bề mặt provider mà hệ thống mong đợi, đồng thời tuân theo layout package, chiến lược test và các pattern triển khai đang dùng trong repo.

Ai nên dùng add-provider-package

Hãy dùng add-provider-package nếu bạn đang:

• Thêm một model provider mới vào monorepo vercel/ai
• Xây dựng một third-party provider package dựa theo cách các package first-party được tổ chức
• Cố gắng ánh xạ một API bên ngoài vào các abstraction của AI SDK như language model hoặc embeddings
• Cần một lộ trình cụ thể thay vì một prompt kiểu chung chung như “build an adapter”

Kỹ năng này đặc biệt hữu ích nếu bạn đã hiểu HTTP API của provider, nhưng cần hỗ trợ để chuyển nó sang đúng các quy ước package của AI SDK.

Trường hợp sử dụng phù hợp nhất

add-provider-package skill phát huy tác dụng mạnh nhất khi bạn cần:

• Tạo thư mục packages/<provider> mới với cấu trúc đúng như kỳ vọng
• Triển khai các lớp provider theo các interface của @ai-sdk/provider
• Tái sử dụng pattern từ các provider hiện có thay vì tự nghĩ ra cấu trúc riêng
• Hiểu rõ khác biệt giữa first-party và third-party trước khi đầu tư thời gian

Điểm khác biệt chính so với một prompt code thông thường

Một prompt thông thường có thể tạo ra code adapter nháp. add-provider-package có giá trị hơn khi bạn cần hướng dẫn bám sát repository: package nên nằm ở đâu, kiến trúc provider được phân tầng như thế nào, thường có những file gì, và một provider package hoàn chỉnh trong codebase này trông ra sao.

Ràng buộc quan trọng nhất trước khi áp dụng

Kỹ năng này được thiết kế hẹp có chủ đích. Nó dành cho việc tạo package @ai-sdk/<provider>, không phải cho thiết kế API SDK nói chung, các wrapper không liên quan hay hệ plugin tùy ý. Nếu mục tiêu của bạn nằm ngoài kiến trúc provider của AI SDK, add-provider-package sẽ trở nên quá đặc thù.

Cách dùng kỹ năng add-provider-package

Cách cài ngữ cảnh cho add-provider-package

Kỹ năng này nằm trong vercel/ai tại skills/add-provider-package. Trong workflow có hỗ trợ Skills, hãy cài bằng:

npx skills add vercel/ai --skill add-provider-package

Nếu môi trường của bạn đã tự động expose các repository skill, có thể bạn chỉ cần gọi skill theo tên.

Bắt đầu từ đúng file quan trọng nhất

Hãy đọc skills/add-provider-package/SKILL.md trước. Ở snapshot repository này, phần hướng dẫn chính của skill tập trung tại đó, bao gồm:

• kỳ vọng đối với package first-party và third-party
• kiến trúc provider theo từng lớp
• cấu trúc package
• hướng dẫn triển khai từng bước
• một PR tham chiếu làm ví dụ hoàn chỉnh

Vì ở đây không thấy thêm resources/, rules/ hay script hỗ trợ nào khác, nên phần tín hiệu hữu ích nhất nằm trong SKILL.md cùng với các provider package hiện có ở những nơi khác trong monorepo.

add-provider-package cần bạn cung cấp đầu vào gì

Để nhận được kết quả hữu ích, hãy cung cấp thông tin provider một cách cụ thể, thay vì chỉ nói “add support for X.” Bộ đầu vào tối thiểu nên có:

• tên provider và package đích, ví dụ @ai-sdk/acme
• phương thức xác thực API
• các loại model được hỗ trợ: chat, completion, embeddings, image, v.v.
• hành vi streaming
• schema request và response
• định dạng lỗi và cách provider xử lý rate limit
• các điểm đặc thù của provider, như tool calling hoặc khác biệt ở JSON mode

Nếu thiếu các chi tiết này, skill vẫn có thể phác thảo cấu trúc, nhưng không thể định hình adapter một cách đáng tin cậy.

Biến một mục tiêu mơ hồ thành prompt đủ mạnh

Prompt yếu:

Use add-provider-package to add Acme AI to the SDK.

Prompt tốt hơn:

Use add-provider-package to scaffold a new packages/acme provider for vercel/ai. Acme uses API key auth via Authorization: Bearer <key>. It supports text generation and embeddings, with SSE streaming for text. I need the package structure, main source files, likely exports, and the mapping from Acme endpoints to AI SDK model interfaces. Show the repo files I should create first and call out any ambiguous areas I must resolve from the API docs.

Prompt thứ hai hiệu quả hơn vì nó cho skill đủ dữ liệu để chọn đúng bề mặt provider và chỉ ra sớm các rủi ro tích hợp còn chưa rõ.

Quy trình khuyến nghị khi dùng add-provider-package

Một luồng add-provider-package usage thực tế thường là:

1. Xác nhận bạn đang nhắm tới package first-party hay third-party.
2. Đọc SKILL.md để nắm kiến trúc và layout package được kỳ vọng.
3. Xem PR ví dụ được liên kết: https://github.com/vercel/ai/pull/8136/files.
4. Đối chiếu với một hoặc hai provider package hiện có trong packages/.
5. Yêu cầu skill ánh xạ API của provider sang các interface của AI SDK trước khi tạo file.
6. Sau đó mới yêu cầu bộ khung package, kế hoạch triển khai và checklist test.

Trình tự này giúp giảm làm lại vì các sai lệch ở mức interface sẽ được phát hiện trước khi sinh code.

Các đường dẫn trong repo nên xem sau SKILL.md

Để đưa ra quyết định triển khai thực tế, lộ trình đọc tiếp theo thường nên là:

• skills/add-provider-package/SKILL.md
• PR tham chiếu được liên kết bên trong skill
• các phần triển khai packages/<provider>/src/* hiện có trong monorepo
• các interface dùng chung trong @ai-sdk/provider
• các pattern helper trong @ai-sdk/provider-utils

Skill này mô tả rõ kiến trúc phân tầng đó, nên đọc các khu vực trên là cách tốt nhất để kiểm tra code được sinh ra có khớp với pattern hiện tại của repo hay không.

add-provider-package bao quát tốt những gì

add-provider-package guide đặc biệt hữu ích cho các việc sau:

• dựng bộ khung package
• đảm bảo phù hợp về mặt kiến trúc trong AI SDK
• xác định interface provider nào là quan trọng
• hiểu cách mô hình hóa provider như một adapter thay vì viết một client riêng biệt
• dùng một lần bổ sung provider đã có làm triển khai tham chiếu

Những gì add-provider-package không quyết định thay bạn

Skill này không thể thay thế việc bạn tự đọc và diễn giải tài liệu API của provider gốc. Bạn vẫn phải tự quyết định:

• năng lực nào xứng đáng được hỗ trợ ở mức first-class
• nên xử lý các request option đặc thù của provider như thế nào
• sẽ expose những model nào
• cách chuyển đổi các lỗi không chuẩn và payload streaming
• liệu các tính năng chưa được hỗ trợ nên bị lược bỏ hay được đưa ra sau các option đặc thù của provider

Mẫu prompt thực tế cho add-provider-package trong phát triển API

Nếu bạn dùng add-provider-package for API Development, hãy yêu cầu đầu ra theo đúng thứ tự ra quyết định:

1. ánh xạ năng lực
2. kế hoạch package/file
3. kế hoạch type/interface
4. kế hoạch chuyển đổi request/response
5. test và edge case

Ví dụ:

Use add-provider-package to plan an @ai-sdk/zen package. First, map Zen's endpoints to AI SDK interfaces. Second, propose the package file tree. Third, list the core transforms for text generation, embeddings, and streaming. Finally, list the top 10 edge cases to test.

Cách này cho ra kết quả dễ triển khai hơn nhiều so với việc yêu cầu đổ ra toàn bộ code ngay từ đầu.

Những điểm nghẽn thường gặp trước khi bắt đầu code

Các trở ngại lớn nhất thường không nằm ở lỗi cú pháp, mà ở những quyết định sản phẩm còn thiếu:

• Đây là package first-party hay third-party?
• API của provider có thực sự khớp sạch với các abstraction của AI SDK không?
• Event streaming có đủ ổn định để adapter hóa không?
• Những khả năng model nào đã đủ chín để đưa ra public?
• Có provider nào sẵn có với hình dạng API gần giống hơn để bạn sao theo không?

Hãy dùng skill sớm để lôi các câu hỏi này ra trước khi bắt tay dựng package.

Câu hỏi thường gặp về kỹ năng add-provider-package

add-provider-package có chỉ dành cho maintainer của Vercel không?

Không. Skill này cũng hữu ích cho contributor bên ngoài và tác giả third-party package. Nguồn gốc nội dung phân biệt rõ third-party package với các package first-party @ai-sdk/<provider>, đồng thời lưu ý rằng các phần bổ sung first-party nên được thảo luận trước.

add-provider-package có phù hợp cho người mới không?

Có thể dùng được với người mới nếu họ đã nắm API của provider mục tiêu, nhưng đây không phải tutorial nhập môn về TypeScript, package publishing hay thiết kế SDK. Giá trị lớn nhất của nó nằm ở phần hướng dẫn bám repo và đảm bảo phù hợp về mặt kiến trúc.

add-provider-package khác gì so với việc chỉ nhờ một LLM viết wrapper provider?

Một prompt thông thường có thể tạo ra đoạn code nhìn có vẻ hợp lý nhưng lại không khớp với cấu trúc package hoặc interface của AI SDK. add-provider-package skill neo công việc vào kiến trúc adapter của monorepo và chỉ cho bạn một triển khai tham chiếu cụ thể.

Có thể dùng add-provider-package ngoài repo vercel/ai không?

Có, như một mẫu tham chiếu. Nhưng dự án của bạn càng gần với abstraction provider và layout package của AI SDK thì đầu ra càng dễ tái sử dụng. Nếu codebase của bạn dùng interface hoặc quy ước publish khác, hãy chuẩn bị cho phần điều chỉnh thêm.

Khi nào không nên dùng add-provider-package?

Bỏ qua skill này nếu bạn đang:

• xây một API client đa dụng
• tích hợp provider ngoài mô hình AI SDK
• tìm ví dụ frontend app thay vì code provider package
• chưa sẵn sàng kiểm tra các triển khai provider hiện có để đảm bảo tương đương

add-provider-package có gồm ví dụ end-to-end đầy đủ không?

Có một tham chiếu tới một lần bổ sung provider hoàn chỉnh thông qua PR: https://github.com/vercel/ai/pull/8136/files. Đây là một trong những phần giá trị nhất của skill vì nó cho thấy một bổ sung hoàn chỉnh trông như thế nào trong ngữ cảnh thực tế.

Cách cải thiện kỹ năng add-provider-package

Cung cấp đầu vào ở mức capability cho add-provider-package

Cách nhanh nhất để nâng chất lượng đầu ra là mô tả chính xác năng lực của provider. Thay vì chỉ nói “supports chat”, hãy cung cấp:

• tên endpoint
• giao thức streaming
• hỗ trợ tool calling
• hành vi của structured output
• số chiều embeddings hoặc định dạng request
• auth và header
• các điểm đặc thù về retry hoặc rate limit

Nhờ vậy, skill có thể suy luận về độ phù hợp của interface thay vì đoán từ các thuật ngữ marketing.

Yêu cầu phân tích khoảng trống trước khi sinh code

Một bước mở đầu rất hiệu quả là:

Use add-provider-package to identify the gaps between this provider API and AI SDK expectations before proposing code.

Trong nhiều trường hợp, cách này tốt hơn yêu cầu scaffold ngay lập tức, vì nó làm lộ ra các tính năng còn thiếu, định dạng streaming không tương thích hoặc những chỗ buộc phải dùng option riêng của provider.

Tham chiếu một provider tương tự đang có sẵn

Nếu bạn biết trong vercel/ai đã có provider nào có hình dạng API tương tự, hãy nói rõ điều đó. Ví dụ:

Use add-provider-package and model this after the provider package that has the closest SSE text streaming and embeddings support.

Điều này giúp đầu ra nhất quán hơn và giảm nguy cơ skill tự bịa ra abstraction không cần thiết.

Yêu cầu đầu ra theo từng file, không dồn vào một bản nháp khổng lồ

Skill sẽ dễ kiểm chứng hơn nếu bạn yêu cầu lần lượt:

• cây thư mục package
• src/index.ts exports
• provider factory
• các file triển khai model
• tests
• metadata của package

Cách này giúp quá trình review đáng tin cậy hơn so với việc tạo cả package trong một lần.

Các lỗi thường gặp cần soi kỹ

Khi dùng add-provider-package, hãy rà soát đầu ra để phát hiện:

• các capability chưa thật sự được hỗ trợ nhưng lại được expose như đã ổn định
• phần streaming được ánh xạ quá lạc quan
• option đặc thù của provider bị rò vào generic interface
• thiếu chuẩn hóa lỗi
• cấu trúc package không khớp với quy ước hiện có trong repo
• code bỏ qua khác biệt quy trình giữa first-party và third-party

Cải thiện prompt bằng các mẫu API cụ thể

Nếu kết quả đầu tiên còn quá trừu tượng, hãy thêm các mẫu request và response thật từ tài liệu provider. Đây là một trong những cách tăng chất lượng mạnh nhất, vì sống còn của provider package nằm ở độ chính xác của phần chuyển đổi.

Prompt tiếp theo tốt có thể là:

Here are the exact JSON request and SSE response shapes for text generation. Revise the add-provider-package plan so the model implementation and streaming parser match these payloads.

Lặp lại một cách tường minh với các quyết định chưa chốt

Sau lượt đầu tiên, hãy yêu cầu skill tách riêng:

• các bước triển khai có độ chắc chắn cao
• các giả định
• các câu hỏi mở cần xác minh bằng tài liệu provider
• các test có khả năng cần viết

Cấu trúc này giúp skill dễ hành động hơn và giảm phần phỏng đoán ẩn.

Cách tốt nhất để xác thực đầu ra của add-provider-package

Hãy coi đầu ra như một kế hoạch triển khai bám sát repo, rồi kiểm chứng nó với:

• SKILL.md
• PR tham chiếu được liên kết
• một hoặc hai provider package hiện có
• các interface trong @ai-sdk/provider
• tài liệu API chính thức của provider mục tiêu

Vòng lặp xác thực đó là cách tốt nhất để biến add-provider-package usage từ mức “bản nháp hữu ích” thành một package mà bạn thực sự có thể merge hoặc publish.