develop-ai-functions-example

Tổng quan về skill develop-ai-functions-example

develop-ai-functions-example dùng để làm gì

develop-ai-functions-example là một hướng dẫn build chuyên biệt để tạo mới hoặc chỉnh sửa các ví dụ có thể chạy được trong examples/ai-functions/src/ của repo vercel/ai. Skill này không dành cho prompting tổng quát. Nó giúp bạn tạo ra các ví dụ bám đúng quy ước của repo cho demo function trong AI SDK, kiểm tra tính hỗ trợ của provider và các fixture mang tính test.

Ai nên dùng skill này

Hãy dùng develop-ai-functions-example nếu bạn đang:

• thêm một ví dụ mới cho một function của AI SDK
• điều chỉnh một ví dụ sang provider khác
• kiểm tra xem một provider có hỗ trợ một tính năng hay không
• tạo một minimal repro hoặc fixture trong cây ví dụ hiện có
• muốn bám theo cấu trúc repo thay vì tự nghĩ ra pattern riêng

Nếu bạn chỉ muốn hỏi một LLM generateText() hoạt động ra sao ở mức khái niệm, thì skill này có lẽ hẹp hơn nhu cầu của bạn.

Công việc thực sự mà skill này giải quyết

Phần lớn người dùng không cần văn bản giải thích dài dòng. Họ cần một ví dụ chạy được, nằm đúng thư mục, có đúng cấu trúc, dùng đúng function của SDK và ít mắc lỗi đặc thù của repo hơn. Tốt nhất nên xem develop-ai-functions-example như một trợ lý triển khai có nhận thức về repo cho khu vực ví dụ AI Functions.

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

Một prompt chung chung vẫn có thể phác thảo code ví dụ, nhưng thường bỏ lỡ taxonomy nội bộ và logic đặt file của repo. Skill này bổ sung bối cảnh thực tế như:

• các nhóm ví dụ đã có sẵn dưới examples/ai-functions/src/
• cách ánh xạ mong đợi giữa loại tính năng và thư mục đích
• mục đích của các ví dụ trong repo: validation, demonstration và fixtures
• xu hướng ưu tiên ví dụ tối giản, chạy được thay vì tutorial quá rộng

Phạm vi phù hợp nhất

develop-ai-functions-example for Skill Examples phát huy hiệu quả nhất với các nhóm công việc sau:

• generate-text/
• stream-text/
• generate-object/
• stream-object/
• agent/
• embed/
• embed-many/
• generate-image/
• generate-speech/
• transcribe/
• rerank/
• middleware/

Phạm vi này rất quan trọng. Skill được tối ưu cho việc phát triển example bên trong cấu trúc repo này, chứ không phải để thiết kế ứng dụng, bề mặt API của SDK hay kiến trúc production.

Cách dùng skill develop-ai-functions-example

Bối cảnh cài đặt và nơi áp dụng

Hãy dùng hướng dẫn develop-ai-functions-example install trong bối cảnh repo vercel/ai, hoặc khi bạn muốn mô phỏng lại cấu trúc example của repo này. Một cách thiết lập phổ biến là:

npx skills add vercel/ai --skill develop-ai-functions-example

Sau đó gọi skill khi tác vụ của bạn thực sự xoay quanh việc tạo, chỉnh sửa hoặc kiểm tra các file ví dụ dưới examples/ai-functions/src/.

Bắt đầu bằng cách chọn đúng nhóm example

Trước khi yêu cầu viết code, hãy xác định đúng họ function mục tiêu. Đây là quyết định mang lại hiệu quả cao nhất vì nó quyết định cả thư mục lẫn dạng ví dụ cần tạo.

Ví dụ:

• đầu ra văn bản one-shot đơn giản → generate-text/
• streaming theo token hoặc chunk → stream-text/
• đầu ra có cấu trúc, bị ràng buộc bởi schema → generate-object/
• đầu ra có cấu trúc theo kiểu streamed → stream-object/
• embeddings cho một đầu vào → embed/
• embeddings cho theo lô → embed-many/
• workflow nhiều bước có dùng tool → agent/

Nếu bỏ qua bước này, ví dụ được tạo ra có thể dùng sai API ngay từ đầu.

Skill cần bạn cung cấp những gì

Chất lượng của develop-ai-functions-example usage phụ thuộc nhiều vào mức độ cụ thể trong yêu cầu của bạn. Hãy cung cấp:

• function mục tiêu, chẳng hạn generateObject() hoặc streamText()
• provider và model, nếu đã biết
• ví dụ này phục vụ validation, demo kiểu docs hay test fixture
• đầu vào và đầu ra mong đợi
• có cần streaming, tools, schema validation hay middleware hay không
• mọi ràng buộc về dependency, cách đặt tên file hoặc biến môi trường

Một đầu vào còn yếu:

• “Make an AI example.”

Một đầu vào mạnh hơn:

• “Create a minimal generateObject() example under examples/ai-functions/src/generate-object/ that tests structured extraction from product review text using a Zod schema and a provider supported in this repo.”

Biến mục tiêu thô thành prompt phù hợp với skill

Một prompt develop-ai-functions-example guide tốt nên nêu rõ kết quả cần có, thư mục đích, function cần dùng và mục tiêu validation.

Mẫu hữu ích:

• bạn muốn tạo cái gì
• nó nên nằm ở đâu
• nó cần dùng function nào của AI SDK
• được phép giả định gì về provider
• cần tối giản hay gần với production tới mức nào
• thế nào thì được xem là thành công

Ví dụ prompt:

“Use develop-ai-functions-example to create a minimal example in examples/ai-functions/src/stream-text/ showing streamText() with a provider already used in the repo. Keep it short, runnable, and clearly focused on streaming output rather than app integration. Include any required env vars and explain why this belongs in stream-text/ instead of generate-text/.”

Đọc SKILL.md trước, rồi xem các example lân cận

Skill này chỉ có một file hỗ trợ hiển thị công khai: SKILL.md. Hãy đọc file này trước vì nó tóm tắt bản đồ category và mục đích riêng của repo. Sau đó, xem các example lân cận trong thư mục đích mà bạn định chỉnh sửa. Cách này giúp bạn nắm được pattern đặt tên và code tại chỗ nhanh hơn nhiều so với việc đọc tài liệu tổng quát của repo.

Thứ tự đọc thực tế nên là:

1. skills/develop-ai-functions-example/SKILL.md
2. thư mục đích dưới examples/ai-functions/src/
3. một hoặc hai example cùng cấp gần nhất với tính năng bạn định làm
4. mọi import theo provider hoặc pattern env được dùng ở khu vực lân cận

Khớp example với đúng mục đích

Repo này dùng example không chỉ để làm tài liệu. Prompt của bạn nên nói rõ đang tối ưu cho mục tiêu nào trong số sau:

• validation tính hỗ trợ của provider
• demo tính năng
• fixture có thể tái lập
• thử nghiệm lặp

Vì sao điều này quan trọng:

• example phục vụ validation nên tối giản và tường minh
• example dạng demo nên làm nổi bật hành vi API cốt lõi
• fixture nên tránh các biến thể không cần thiết
• bản thử nghiệm có thể thô hơn, nhưng vẫn phải nằm đúng thư mục

Giữ đầu ra tối giản nhưng vẫn chạy được

Những đầu ra tốt nhất của develop-ai-functions-example skill thường làm ít hơn, không phải nhiều hơn. Hãy yêu cầu:

• một lời gọi function rõ ràng
• chỉ import những gì thực sự cần
• đầu vào dễ hiểu
• xử lý đầu ra gọn nhẹ
• nêu rõ các biến môi trường cần thiết
• không thêm framework scaffolding trừ khi thư mục đó vốn đã cần

Cách này giúp giảm các trường hợp model chèn thêm code ứng dụng làm che mất hành vi thực sự của SDK mà bạn muốn minh hoạ.

Các đường dẫn repo nên nêu rõ

Nếu muốn đầu ra bám sát repo, hãy nêu trực tiếp path trong yêu cầu. Một số path hữu ích gồm:

• examples/ai-functions/src/generate-text/
• examples/ai-functions/src/stream-text/
• examples/ai-functions/src/generate-object/
• examples/ai-functions/src/stream-object/
• examples/ai-functions/src/agent/
• examples/ai-functions/src/embed/
• examples/ai-functions/src/embed-many/

Việc chỉ rõ path giúp skill chọn đúng pattern thay vì tự dựng ra một ví dụ trung tính không bám repo.

Quy trình thực tế để tạo một example mới

Một quy trình đáng tin cậy là:

1. xác định đúng họ function mục tiêu
2. xem các example cùng cấp trong thư mục đó
3. prompt cho skill với thư mục, function, provider và mục đích
4. tạo bản example đầu tiên
5. cắt bỏ mọi thứ không cần cho validation hoặc demonstration
6. chạy thử với provider dự định dùng
7. chỉnh lại cách đặt tên, đầu vào và xử lý env để khớp các file lân cận

Cách này thường nhanh hơn so với việc yêu cầu một ví dụ hoàn chỉnh trong trạng thái mù, rồi mới cố retrofit nó vào repo.

Khi nào nên dùng skill này thay cho prompt thông thường

Hãy dùng develop-ai-functions-example usage khi rủi ro chính là lệch repo: sai thư mục, sai function của AI SDK, độ phức tạp không đúng mức, hoặc một bản demo không khớp với cây examples. Hãy dùng prompt thông thường khi bạn cần hỗ trợ kiến trúc rộng hơn ngoài phạm vi examples/ai-functions/src/.

Câu hỏi thường gặp về skill develop-ai-functions-example

develop-ai-functions-example có chỉ dành cho repo vercel/ai không

Skill này hữu ích nhất ở đó vì nó bám chặt vào taxonomy example trong examples/ai-functions/src/. Bạn vẫn có thể dùng nó như một pattern cho repo examples của riêng mình, nhưng giá trị sẽ giảm đi nếu bạn không quan tâm đến việc khớp cấu trúc này.

Skill này có thân thiện với người mới bắt đầu không

Có, nếu bạn đã biết tính năng mình muốn minh hoạ là gì. Nó thu hẹp không gian lựa chọn bằng cách ánh xạ mục tiêu của bạn vào đúng category example. Nó sẽ kém thân thiện hơn nếu bạn vẫn còn đang phân vân giữa text generation, structured generation, embeddings, agents hay middleware.

Nó làm tốt hơn yêu cầu code thông thường ở điểm nào

Lợi thế chính là mức độ khớp repo tốt hơn. develop-ai-functions-example giúp bạn tránh những lỗi như đặt một ví dụ structured output vào thư mục plain text, dùng API không streaming cho một demo streaming, hoặc dựng một fixture quá cồng kềnh kèm theo code ứng dụng không liên quan.

Khi nào tôi không nên dùng develop-ai-functions-example

Đừng dùng nó khi bạn cần:

• kiến trúc ứng dụng production
• hướng dẫn tích hợp UI
• một tutorial AI SDK tổng quát
• tư vấn refactor xuyên nhiều repo
• chiến lược evaluation hoặc benchmarking vượt ra ngoài phạm vi tạo example

Skill này được thiết kế hẹp có chủ đích.

Tôi có cần biết chính xác provider ngay từ đầu không

Không hẳn, nhưng đầu ra sẽ tốt hơn nếu bạn chỉ rõ một provider. Nếu chưa biết, hãy yêu cầu dùng một provider đã xuất hiện trong các example lân cận để file được tạo ra dễ kiểm tra hơn theo các pattern sẵn có của repo.

Nó có giúp chỉnh sửa example hiện có, hay chỉ tạo mới

Có. Skill này hữu ích cả khi chỉnh sửa hoặc siết gọn một example đang có, đặc biệt khi bạn muốn đổi function SDK, thay provider, đơn giản hoá một repro hoặc căn lại file vào đúng category.

Cách cải thiện skill develop-ai-functions-example

Cung cấp đích repo thật cụ thể cho skill

Cách cải thiện hiệu quả nhất là nêu chính xác thư mục đích và function cần dùng. So sánh:

Yếu:

• “Add an example for object extraction.”

Mạnh:

• “Use develop-ai-functions-example to add a minimal generateObject() example under examples/ai-functions/src/generate-object/ that extracts invoice fields from plain text and prints validated JSON.”

Phiên bản mạnh hơn loại bỏ sự mơ hồ về lựa chọn API và vị trí đặt file.

Nói rõ mục đích của đầu ra ngay từ đầu

Điều người dùng quan tâm nhất là example này nhằm chứng minh khả năng hỗ trợ, hướng dẫn cách dùng hay đóng vai trò fixture. Hãy đưa thông tin đó vào câu đầu tiên của prompt. Hình dạng code thường thay đổi theo chính quyết định này.

Ngăn tình trạng overengineering ngay ở bản nháp đầu tiên

Một lỗi phổ biến là nhận về câu trả lời có thêm wrapper, app scaffolding hoặc trộn nhiều mối quan tâm. Hãy yêu cầu rõ:

• code tối giản
• một trách nhiệm duy nhất
• không có UI
• không setup framework
• chỉ giữ lại comment thật sự cần thiết

Nhờ vậy example sẽ bám cây examples thay vì biến thành một mini app.

Yêu cầu bám pattern cục bộ

Để cải thiện kết quả của develop-ai-functions-example skill, hãy bảo model bắt chước các example lân cận về cách đặt tên, import và xử lý env. Chỉ dẫn nhỏ này thường quan trọng hơn cả việc yêu cầu “best practices”.

Ví dụ:

• “Match the style of sibling files in examples/ai-functions/src/stream-text/ and avoid introducing a new pattern unless required.”

Nêu rõ đầu vào và dạng đầu ra mong đợi

Một lỗi thường gặp khác là logic demo quá mơ hồ. Nếu bạn chỉ rõ input mẫu và output mong đợi, example sẽ dễ kiểm tra hơn.

Chi tiết prompt tốt hơn nên có:

• văn bản đầu vào hoặc payload
• dạng phản hồi mong đợi
• đầu ra có cần streamed, logged hay schema-validated không
• điều gì được tính là thành công

Lặp lại theo hướng siết chặt, không phải mở rộng

Sau bản nháp đầu tiên, hãy cải thiện bằng cách giảm bớt mơ hồ:

• thay “some provider” bằng một provider cụ thể
• thay “an object” bằng một schema
• thay “example script” bằng thư mục đích
• thay “works” bằng một kỳ vọng đầu ra có thể kiểm chứng

Con đường lặp tối ưu cho develop-ai-functions-example thường là thu hẹp phạm vi, không phải thêm tính năng.

Kiểm tra độ phù hợp với category trước khi chấp nhận kết quả

Trước khi giữ lại kết quả, hãy tự hỏi:

• Đây có phải đúng thư mục cho function đang dùng không?
• Example này đã đủ tối giản cho mục đích validation chưa?
• Nó có minh hoạ rõ một hành vi cốt lõi duy nhất không?
• Một maintainer có hiểu ngay vì sao file này thuộc về đây không?

Nếu chưa, hãy sửa prompt trước khi sửa code. Thường đó mới là cách khắc phục nhanh hơn.

Cải thiện prompt bằng giả định về provider và môi trường

Nếu example phụ thuộc vào credentials hoặc hành vi riêng của provider, hãy nói thẳng điều đó. Nếu không, model có thể tạo ra code nghe hợp lý về mặt kỹ thuật nhưng lại khó chạy trong repo.

Những bổ sung hữu ích gồm:

• tên các env var bắt buộc
• giả định về provider SDK
• tên model nếu tính ổn định quan trọng
• có chấp nhận fallback hay không

Dùng các example cùng cấp làm tiêu chí nghiệm thu

Một cách thực tế để nâng chất lượng đầu ra là đánh giá file được tạo ra dựa trên các example lân cận, không phải theo tiêu chuẩn code chung chung. Nếu nó có vẻ phức tạp hơn hẳn, kém tập trung hơn hoặc khác cấu trúc so với các file cùng cấp, hãy yêu cầu viết lại để khớp pattern cục bộ.