building-inferencesh-apps

Tổng quan

building-inferencesh-apps là gì?

Kỹ năng building-inferencesh-apps là một hướng dẫn tập trung vào việc tạo và triển khai ứng dụng trên nền tảng inference.sh. Nội dung giải thích quy trình chuẩn của một app, vai trò của infsh CLI và cách scaffold cũng như quản lý các ứng dụng dạng backend viết bằng Python hoặc Node.js một cách an toàn.

Đây không phải là một tutorial tổng quát; nó được thiết kế bám sát các lệnh infsh app chính thức và các yêu cầu của runtime inference.sh. Kỹ năng này giúp bạn tránh các lỗi phổ biến như tự tạo thủ công các tệp cốt lõi, cấu hình sai tài nguyên của app hoặc deploy từ nhầm thư mục.

Kỹ năng này dành cho ai?

Hãy sử dụng building-inferencesh-apps nếu bạn là:

• Backend developer xây dựng các app kiểu API chạy trên inference.sh
• Kỹ sư Python hoặc Node.js đang wrap model hoặc external API thành một dịch vụ được host
• Developer ưu tiên CLI, muốn có quy trình triển khai có thể dự đoán và script được
• Người dùng nền tảng cần hiểu ở mức khái quát về GPU/VRAM, secrets của app và các tích hợp

Nếu bạn cần hiểu một ứng dụng inference.sh nên được tổ chức như thế nào, cách các tệp inf.yml và inference.py / inference.js được tạo ra, và cách làm việc với nền tảng một cách an toàn, thì kỹ năng này là điểm bắt đầu phù hợp.

Kỹ năng này giải quyết những vấn đề gì?

Kỹ năng building-inferencesh-apps giải quyết những vướng mắc thường gặp khi bắt đầu phát triển app trên inference.sh:

• Không rõ cách scaffold một app mới cho đúng chuẩn
• Tự tạo thủ công inf.yml, inference.py, inference.js hoặc package.json dẫn đến xung đột với yêu cầu của nền tảng
• Quên cd vào thư mục app trước khi chạy các lệnh infsh
• Mất dữ liệu output_meta vì extend nhầm base class
• Thiếu logging khiến việc debug các app chạy từ xa/đậm đặc API trở nên khó khăn

Bằng cách làm theo các thực hành được tóm tắt trong kỹ năng này, bạn có được một quy trình nhất quán và lặp lại được để xây dựng và triển khai app trên inference.sh.

Khi nào nên dùng building-inferencesh-apps?

Kỹ năng này đặc biệt phù hợp khi:

• Bạn đang bắt đầu một app mới trên inference.sh và muốn đi theo quy trình chuẩn
• Bạn đã có infsh CLI hoặc dự định cài đặt nó và điều khiển mọi thứ từ dòng lệnh
• Bạn muốn xây dựng backend Python hoặc Node.js, bao gồm cả các wrapper quanh external API hoặc model

Kỹ năng này sẽ ít hữu ích hơn khi:

• Bạn không dùng inference.sh làm môi trường triển khai
• Bạn chỉ cần code phía client hoặc pattern UI front-end
• Bạn mong đợi một GUI kiểu point-and-click thay vì workflow dựa trên CLI

Nếu mục tiêu chính của bạn là triển khai backend và API ổn định, tự động trên inference.sh, building-inferencesh-apps rất phù hợp với nhu cầu đó.

Cách sử dụng

1. Cài đặt inference.sh CLI

Kỹ năng building-inferencesh-apps giả định bạn dùng CLI chính thức của inference.sh, infsh, cho mọi thao tác với app.

Cài CLI

Chạy script cài đặt từ terminal:

curl -fsSL https://cli.inference.sh | sh

Sau khi cài đặt, cập nhật lên phiên bản mới nhất khi cần:

infsh update

Hãy giữ CLI luôn cập nhật để việc scaffold app và hành vi deploy phù hợp với yêu cầu hiện tại của nền tảng.

2. Thêm kỹ năng building-inferencesh-apps

Cài kỹ năng này vào môi trường agent của bạn để agent có thể tham chiếu bộ quy tắc và hướng dẫn đã được tuyển chọn:

npx skills add https://github.com/inferen-sh/skills --skill building-apps

Lệnh này liên kết agent của bạn với nội dung sdk/building-apps trong repository inferen-sh/skills, biến các quy tắc xây app thành một khả năng có thể tái sử dụng.

3. Scaffold app bằng infsh app init (không làm thủ công)

Quy tắc cốt lõi trong building-inferencesh-apps là mọi app đều phải được scaffold bằng CLI. Nền tảng mong đợi các tệp và cấu trúc nhất định mà CLI sẽ tạo sẵn cho bạn.

Quy tắc scaffold bắt buộc

• Không tự tạo thủ công:
  • inf.yml
  • inference.py
  • inference.js
  • __init__.py
  • package.json
  • Thư mục app
• Bỏ qua mọi tài liệu hoặc file cấu trúc local khuyến nghị scaffold thủ công (ví dụ PROVIDER_STRUCTURE.md).

Thay vào đó, luôn sử dụng:

infsh app init

CLI sẽ tạo đúng cấu trúc thư mục và các tệp cốt lõi cần thiết cho một app inference.sh hợp lệ, dù bạn dùng Python hay Node.js.

4. Làm việc từ đúng thư mục app

Kỹ năng building-inferencesh-apps nhấn mạnh rằng thư mục làm việc của shell là yếu tố quyết định cho mọi lệnh infsh:

• Luôn cd vào thư mục app trước khi chạy các lệnh infsh như init, deploy hoặc test.
• Thư mục làm việc của shell không được giữ lại giữa các lần gọi tool riêng biệt, nghĩa là mọi automation hoặc agent dùng kỹ năng này đều phải chủ động đổi thư mục mỗi lần.

Mẫu điển hình:

cd path/to/your-app
infsh app deploy

Nếu bạn bỏ qua cd, bạn có nguy cơ deploy hoặc test nhầm app, hoặc gặp lỗi khó hiểu vì inf.yml không tồn tại trong thư mục hiện tại.

5. Định nghĩa output đúng cách trong app Python

Với các app Python có metadata trong output, building-inferencesh-apps đưa ra một quy tắc quan trọng:

• Nếu class output của bạn dùng output_meta, nó bắt buộc phải extend BaseAppOutput.
• Không được extend BaseModel cho những output này.

Nếu bạn extend BaseModel, mọi trường output_meta sẽ bị loại bỏ khỏi response mà không báo lỗi. Sử dụng BaseAppOutput đảm bảo cả dữ liệu và metadata liên quan đều được giữ lại và được runtime trả về đầy đủ.

6. Thêm logging trong run() để dễ quan sát

Kỹ năng này khuyến nghị bật logging mặc định trong method run() của app:

• Dùng self.logger.info(...) bên trong run() để ghi nhận các sự kiện chính, thời gian xử lý, và tóm tắt request/response.
• Điều này đặc biệt quan trọng với các app wrap API, nơi phần xử lý nặng diễn ra ở dịch vụ bên ngoài chứ không phải trong code của bạn.

Các pattern tiêu biểu nên có logging:

• Đo độ trễ (latency) của các lần gọi model upstream
• Ghi nhận những endpoint external API đã được gọi
• Theo dõi kích thước request hoặc các tham số liên quan đến việc sử dụng GPU/VRAM

Logging nhất quán giúp bạn debug vấn đề hiệu năng và hiểu rõ cách backend inference.sh của bạn hoạt động trong môi trường production.

7. Quy trình phát triển và triển khai điển hình

Dù trích đoạn repository tập trung vào các quy tắc, bạn có thể dùng building-inferencesh-apps như một checklist trong đầu cho workflow tiêu chuẩn:

1. Cài đặt infsh CLI.
2. Khởi tạo app mới bằng infsh app init (Python hoặc Node.js).
3. Đổi thư mục vào folder app vừa tạo trước khi chạy bất kỳ lệnh nào tiếp theo.
4. Hiện thực logic app trong các file đã được tạo, tuân thủ quy tắc BaseAppOutput cho các output có output_meta và thêm logging với self.logger.info(...).
5. Cấu hình tài nguyên (như GPU/VRAM và các tích hợp) thông qua cấu hình do CLI tạo, không tự tạo inf.yml bằng tay.
6. Deploy và test bằng các lệnh infsh từ bên trong thư mục app.

Mỗi khi bạn mở rộng hoặc tự động hóa workflow này, hãy giữ nguyên các quy tắc: dựa vào CLI để tạo cấu trúc, luôn đảm bảo đúng thư mục làm việc, và duy trì pattern nhất quán cho output và logging.

FAQ

building-inferencesh-apps có chỉ dành cho Python không?

Không. Kỹ năng building-inferencesh-apps bao phủ các ứng dụng trên inference.sh có thể được viết bằng Python hoặc Node.js. Cùng một CLI (infsh app init) được dùng để scaffold cho cả hai, và các hướng dẫn về xử lý thư mục cũng như cách dùng CLI áp dụng chung cho cả hai ngôn ngữ.

Tại sao tôi không được tự tạo inf.yml hoặc inference.py?

Nền tảng inference.sh yêu cầu cấu trúc, các field và quan hệ giữa file rất cụ thể. Việc tự tạo inf.yml, inference.py, inference.js, package.json hoặc thư mục app có thể dẫn đến các lỗi cấu hình khó phát hiện. Kỹ năng building-inferencesh-apps yêu cầu dùng infsh app init vì CLI sẽ sinh ra layout hợp lệ, cập nhật, tương thích với yêu cầu hiện tại của nền tảng.

Nếu tôi quên cd vào thư mục app thì sao?

Nếu bạn chạy lệnh infsh từ sai thư mục, CLI có thể:

• Thao tác trên nhầm app
• Không tìm thấy inf.yml hoặc các file lõi của app
• Sinh ra lỗi khó hiểu hoặc deploy một app khác với app bạn mong đợi

Để tránh tình trạng này, kỹ năng building-inferencesh-apps coi cd path/to/app là bước bắt buộc trước mọi lệnh infsh, đặc biệt trong các workflow dùng script hoặc agent.

Tôi nên tổ chức các output class dùng output_meta như thế nào?

Với app Python:

• Bất kỳ output class nào có output_meta đều phải extend BaseAppOutput.
• Tránh dùng BaseModel cho các output này, vì nó sẽ âm thầm loại bỏ output_meta khỏi response.

Tuân thủ quy tắc này giúp metadata được giữ nguyên và trả về chính xác bởi inference.sh.

Tại sao kỹ năng này nhấn mạnh logging trong run()?

Building-inferencesh-apps nhấn mạnh logging vì nhiều app trên inference.sh là API wrapper hoặc phụ thuộc mạnh vào dịch vụ bên ngoài. Nếu không có logging qua self.logger.info(...) bên trong run(), bạn sẽ rất khó:

• Chẩn đoán vấn đề latency và hiệu năng
• Hiểu nguyên nhân lỗi từ các API upstream
• Liên kết request với response khi debug

Thêm các log mức info cơ bản ngay từ đầu sẽ giúp bạn có đủ tín hiệu để quan sát hoạt động của backend trong từng request.

Kỹ năng này có giải thích chi tiết các thiết lập GPU và VRAM không?

Kỹ năng này tập trung vào workflow và quy tắc cho phát triển app trên inference.sh: scaffold bằng CLI, quản lý thư mục, yêu cầu với output class và logging. Nó được thiết kế để bạn suy nghĩ đúng về tài nguyên app như GPU, VRAM, secrets và các tích hợp, nhưng trích đoạn repository hiện tại nhấn mạnh vào các quy tắc hơn là ví dụ cấu hình chi tiết. Để cấu hình tài nguyên cụ thể, hãy kết hợp hướng dẫn workflow của kỹ năng này với tài liệu chính thức của inference.sh.

Khi nào không nên dùng building-inferencesh-apps?

Kỹ năng này không phù hợp nếu:

• Bạn không triển khai lên inference.sh
• Bạn cần hướng dẫn về framework front-end hoặc UI hơn là backend
• Bạn thích tự tạo file và thư mục thủ công thay vì workflow dựa trên CLI

Trong hầu hết trường hợp còn lại — đặc biệt khi xây dựng backend kiểu API trên inference.sh — building-inferencesh-apps cung cấp một pattern tin cậy, tập trung vào CLI để bạn có thể làm theo.