Chore/update contributing (#16078)
crazywoola
11 months ago
committed by
GitHub
parent
d339403e89
commit
41dff175b3
@ -1,156 +1,97 @@
|
|||||||
Thật tuyệt vời khi bạn muốn đóng góp cho Dify! Chúng tôi rất mong chờ được thấy những gì bạn sẽ làm. Là một startup với nguồn nhân lực và tài chính hạn chế, chúng tôi có tham vọng lớn là thiết kế quy trình trực quan nhất để xây dựng và quản lý các ứng dụng LLM. Mọi sự giúp đỡ từ cộng đồng đều rất quý giá đối với chúng tôi.
|
# ĐÓNG GÓP
|
||||||
|
|
||||||
Chúng tôi cần linh hoạt và làm việc nhanh chóng, nhưng đồng thời cũng muốn đảm bảo các cộng tác viên như bạn có trải nghiệm đóng góp thuận lợi nhất có thể. Chúng tôi đã tạo ra hướng dẫn đóng góp này nhằm giúp bạn làm quen với codebase và cách chúng tôi làm việc với các cộng tác viên, để bạn có thể nhanh chóng bắt tay vào phần thú vị.
|
Bạn đang muốn đóng góp cho Dify - thật tuyệt vời, chúng tôi rất mong được thấy những gì bạn sẽ làm. Là một startup với nguồn nhân lực và tài chính hạn chế, chúng tôi có tham vọng lớn trong việc thiết kế quy trình trực quan nhất để xây dựng và quản lý các ứng dụng LLM. Mọi sự giúp đỡ từ cộng đồng đều rất có ý nghĩa.
|
||||||
|
|
||||||
Hướng dẫn này, cũng như bản thân Dify, đang trong quá trình cải tiến liên tục. Chúng tôi rất cảm kích sự thông cảm của bạn nếu đôi khi nó không theo kịp dự án thực tế, và chúng tôi luôn hoan nghênh mọi phản hồi để cải thiện.
|
Chúng tôi cần phải nhanh nhẹn và triển khai nhanh chóng, nhưng cũng muốn đảm bảo những người đóng góp như bạn có trải nghiệm đóng góp thuận lợi nhất có thể. Chúng tôi đã tạo hướng dẫn đóng góp này nhằm giúp bạn làm quen với codebase và cách chúng tôi làm việc với người đóng góp, để bạn có thể nhanh chóng bắt đầu phần thú vị.
|
||||||
|
|
||||||
Về vấn đề cấp phép, xin vui lòng dành chút thời gian đọc qua [Thỏa thuận Cấp phép và Đóng góp](./LICENSE) ngắn gọn của chúng tôi. Cộng đồng cũng tuân thủ [quy tắc ứng xử](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md).
|
Hướng dẫn này, giống như Dify, đang được phát triển liên tục. Chúng tôi rất cảm kích sự thông cảm của bạn nếu đôi khi nó chưa theo kịp dự án thực tế, và hoan nghênh mọi phản hồi để cải thiện.
|
||||||
|
|
||||||
## Trước khi bắt đầu
|
Về giấy phép, vui lòng dành chút thời gian đọc [Thỏa thuận Cấp phép và Người đóng góp](./LICENSE) ngắn gọn của chúng tôi. Cộng đồng cũng tuân theo [quy tắc ứng xử](https://github.com/langgenius/.github/blob/main/CODE_OF_CONDUCT.md).
|
||||||
|
|
||||||
[Tìm kiếm](https://github.com/langgenius/dify/issues?q=is:issue+is:open) một vấn đề hiện có, hoặc [tạo mới](https://github.com/langgenius/dify/issues/new/choose) một vấn đề. Chúng tôi phân loại các vấn đề thành 2 loại:
|
|
||||||
|
|
||||||
### Yêu cầu tính năng:
|
## Trước khi bắt đầu
|
||||||
|
|
||||||
* Nếu bạn đang tạo một yêu cầu tính năng mới, chúng tôi muốn bạn giải thích tính năng đề xuất sẽ đạt được điều gì và cung cấp càng nhiều thông tin chi tiết càng tốt. [@perzeusss](https://github.com/perzeuss) đã tạo một [Trợ lý Yêu cầu Tính năng](https://udify.app/chat/MK2kVSnw1gakVwMX) rất hữu ích để giúp bạn soạn thảo nhu cầu của mình. Hãy thử dùng nó nhé.
|
Đang tìm việc để thực hiện? Hãy xem qua [các issue dành cho người mới](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) và chọn một để bắt đầu!
|
||||||
|
|
||||||
* Nếu bạn muốn chọn một vấn đề từ danh sách hiện có, chỉ cần để lại bình luận dưới vấn đề đó nói rằng bạn sẽ làm.
|
Bạn có một model runtime hoặc công cụ mới thú vị để thêm vào? Mở PR trong [repo plugin](https://github.com/langgenius/dify-plugins) của chúng tôi và cho chúng tôi thấy những gì bạn đã xây dựng.
|
||||||
|
|
||||||
Một thành viên trong nhóm làm việc trong lĩnh vực liên quan sẽ được thông báo. Nếu mọi thứ ổn, họ sẽ cho phép bạn bắt đầu code. Chúng tôi yêu cầu bạn chờ đợi cho đến lúc đó trước khi bắt tay vào làm tính năng, để không lãng phí công sức của bạn nếu chúng tôi đề xuất thay đổi.
|
Cần cập nhật model runtime, công cụ hiện có hoặc sửa lỗi? Ghé thăm [repo plugin chính thức](https://github.com/langgenius/dify-official-plugins) và thực hiện phép màu của bạn!
|
||||||
|
|
||||||
Tùy thuộc vào lĩnh vực mà tính năng đề xuất thuộc về, bạn có thể nói chuyện với các thành viên khác nhau trong nhóm. Dưới đây là danh sách các lĩnh vực mà các thành viên trong nhóm chúng tôi đang làm việc hiện tại:
|
Hãy tham gia, đóng góp và cùng nhau xây dựng điều tuyệt vời! 💡✨
|
||||||
|
|
||||||
| Thành viên | Phạm vi |
|
Đừng quên liên kết đến issue hiện có hoặc mở issue mới trong mô tả PR.
|
||||||
| ------------------------------------------------------------ | ---------------------------------------------------- |
|
|
||||||
| [@yeuoly](https://github.com/Yeuoly) | Thiết kế kiến trúc Agents |
|
|
||||||
| [@jyong](https://github.com/JohnJyong) | Thiết kế quy trình RAG |
|
|
||||||
| [@GarfieldDai](https://github.com/GarfieldDai) | Xây dựng quy trình làm việc |
|
|
||||||
| [@iamjoel](https://github.com/iamjoel) & [@zxhlyh](https://github.com/zxhlyh) | Làm cho giao diện người dùng dễ sử dụng |
|
|
||||||
| [@guchenhe](https://github.com/guchenhe) & [@crazywoola](https://github.com/crazywoola) | Trải nghiệm nhà phát triển, đầu mối liên hệ cho mọi vấn đề |
|
|
||||||
| [@takatost](https://github.com/takatost) | Định hướng và kiến trúc tổng thể sản phẩm |
|
|
||||||
|
|
||||||
Cách chúng tôi ưu tiên:
|
### Báo cáo lỗi
|
||||||
|
|
||||||
| Loại tính năng | Mức độ ưu tiên |
|
|
||||||
| ------------------------------------------------------------ | -------------- |
|
|
||||||
| Tính năng ưu tiên cao được gắn nhãn bởi thành viên trong nhóm | Ưu tiên cao |
|
|
||||||
| Yêu cầu tính năng phổ biến từ [bảng phản hồi cộng đồng](https://github.com/langgenius/dify/discussions/categories/feedbacks) của chúng tôi | Ưu tiên trung bình |
|
|
||||||
| Tính năng không quan trọng và cải tiến nhỏ | Ưu tiên thấp |
|
|
||||||
| Có giá trị nhưng không cấp bách | Tính năng tương lai |
|
|
||||||
|
|
||||||
### Những vấn đề khác (ví dụ: báo cáo lỗi, tối ưu hiệu suất, sửa lỗi chính tả):
|
> [!QUAN TRỌNG]
|
||||||
|
> Vui lòng đảm bảo cung cấp các thông tin sau khi gửi báo cáo lỗi:
|
||||||
|
|
||||||
* Bắt đầu code ngay lập tức.
|
- Tiêu đề rõ ràng và mô tả
|
||||||
|
- Mô tả chi tiết về lỗi, bao gồm các thông báo lỗi
|
||||||
|
- Các bước để tái hiện lỗi
|
||||||
|
- Hành vi mong đợi
|
||||||
|
- **Log**, nếu có, cho các vấn đề backend, điều này rất quan trọng, bạn có thể tìm thấy chúng trong docker-compose logs
|
||||||
|
- Ảnh chụp màn hình hoặc video, nếu có thể
|
||||||
|
|
||||||
Cách chúng tôi ưu tiên:
|
Cách chúng tôi ưu tiên:
|
||||||
|
|
||||||
| Loại vấn đề | Mức độ ưu tiên |
|
| Loại vấn đề | Mức độ ưu tiên |
|
||||||
| ------------------------------------------------------------ | -------------- |
|
| ----------- | -------------- |
|
||||||
| Lỗi trong các chức năng chính (không thể đăng nhập, ứng dụng không hoạt động, lỗ hổng bảo mật) | Nghiêm trọng |
|
| Lỗi trong các chức năng cốt lõi (dịch vụ đám mây, không thể đăng nhập, ứng dụng không hoạt động, lỗ hổng bảo mật) | Quan trọng |
|
||||||
| Lỗi không quan trọng, cải thiện hiệu suất | Ưu tiên trung bình |
|
| Lỗi không nghiêm trọng, cải thiện hiệu suất | Ưu tiên trung bình |
|
||||||
| Sửa lỗi nhỏ (lỗi chính tả, giao diện người dùng gây nhầm lẫn nhưng vẫn hoạt động) | Ưu tiên thấp |
|
| Sửa lỗi nhỏ (lỗi chính tả, UI gây nhầm lẫn nhưng vẫn hoạt động) | Ưu tiên thấp |
|
||||||
|
|
||||||
|
|
||||||
## Cài đặt
|
|
||||||
|
|
||||||
Dưới đây là các bước để thiết lập Dify cho việc phát triển:
|
|
||||||
|
|
||||||
### 1. Fork repository này
|
|
||||||
|
|
||||||
### 2. Clone repository
|
|
||||||
|
|
||||||
Clone repository đã fork từ terminal của bạn:
|
|
||||||
|
|
||||||
```
|
### Yêu cầu tính năng
|
||||||
git clone git@github.com:<tên_người_dùng_github>/dify.git
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Kiểm tra các phụ thuộc
|
> [!LƯU Ý]
|
||||||
|
> Vui lòng đảm bảo cung cấp các thông tin sau khi gửi yêu cầu tính năng:
|
||||||
|
|
||||||
Dify yêu cầu các phụ thuộc sau để build, hãy đảm bảo chúng đã được cài đặt trên hệ thống của bạn:
|
- Tiêu đề rõ ràng và mô tả
|
||||||
|
- Mô tả chi tiết về tính năng
|
||||||
|
- Trường hợp sử dụng cho tính năng
|
||||||
|
- Bất kỳ ngữ cảnh hoặc ảnh chụp màn hình nào về yêu cầu tính năng
|
||||||
|
|
||||||
- [Docker](https://www.docker.com/)
|
Cách chúng tôi ưu tiên:
|
||||||
- [Docker Compose](https://docs.docker.com/compose/install/)
|
|
||||||
- [Node.js v18.x (LTS)](http://nodejs.org)
|
|
||||||
- [pnpm](https://pnpm.io/)
|
|
||||||
- [Python](https://www.python.org/) phiên bản 3.11.x hoặc 3.12.x
|
|
||||||
|
|
||||||
### 4. Cài đặt
|
|
||||||
|
|
||||||
Dify bao gồm một backend và một frontend. Đi đến thư mục backend bằng lệnh `cd api/`, sau đó làm theo hướng dẫn trong [README của Backend](api/README.md) để cài đặt. Trong một terminal khác, đi đến thư mục frontend bằng lệnh `cd web/`, sau đó làm theo hướng dẫn trong [README của Frontend](web/README.md) để cài đặt.
|
|
||||||
|
|
||||||
Kiểm tra [FAQ về cài đặt](https://docs.dify.ai/learn-more/faq/install-faq) để xem danh sách các vấn đề thường gặp và các bước khắc phục.
|
|
||||||
|
|
||||||
### 5. Truy cập Dify trong trình duyệt của bạn
|
|
||||||
|
|
||||||
Để xác nhận cài đặt của bạn, hãy truy cập [http://localhost:3000](http://localhost:3000) (địa chỉ mặc định, hoặc URL và cổng bạn đã cấu hình) trong trình duyệt. Bạn sẽ thấy Dify đang chạy.
|
|
||||||
|
|
||||||
## Phát triển
|
|
||||||
|
|
||||||
Nếu bạn đang thêm một nhà cung cấp mô hình, [hướng dẫn này](https://github.com/langgenius/dify/blob/main/api/core/model_runtime/README.md) dành cho bạn.
|
| Loại tính năng | Mức độ ưu tiên |
|
||||||
|
| -------------- | -------------- |
|
||||||
|
| Tính năng ưu tiên cao được gắn nhãn bởi thành viên nhóm | Ưu tiên cao |
|
||||||
|
| Yêu cầu tính năng phổ biến từ [bảng phản hồi cộng đồng](https://github.com/langgenius/dify/discussions/categories/feedbacks) | Ưu tiên trung bình |
|
||||||
|
| Tính năng không cốt lõi và cải tiến nhỏ | Ưu tiên thấp |
|
||||||
|
| Có giá trị nhưng không cấp bách | Tính năng tương lai |
|
||||||
|
|
||||||
Nếu bạn đang thêm một nhà cung cấp công cụ cho Agent hoặc Workflow, [hướng dẫn này](./api/core/tools/README.md) dành cho bạn.
|
## Gửi PR của bạn
|
||||||
|
|
||||||
Để giúp bạn nhanh chóng định hướng phần đóng góp của mình, dưới đây là một bản phác thảo ngắn gọn về cấu trúc backend & frontend của Dify:
|
### Quy trình tạo Pull Request
|
||||||
|
|
||||||
### Backend
|
1. Fork repository
|
||||||
|
2. Trước khi soạn PR, vui lòng tạo issue để thảo luận về các thay đổi bạn muốn thực hiện
|
||||||
|
3. Tạo nhánh mới cho các thay đổi của bạn
|
||||||
|
4. Vui lòng thêm test cho các thay đổi tương ứng
|
||||||
|
5. Đảm bảo code của bạn vượt qua các test hiện có
|
||||||
|
6. Vui lòng liên kết issue trong mô tả PR, `fixes #<số_issue>`
|
||||||
|
7. Được merge!
|
||||||
|
|
||||||
Backend của Dify được viết bằng Python sử dụng [Flask](https://flask.palletsprojects.com/en/3.0.x/). Nó sử dụng [SQLAlchemy](https://www.sqlalchemy.org/) cho ORM và [Celery](https://docs.celeryq.dev/en/stable/getting-started/introduction.html) cho hàng đợi tác vụ. Logic xác thực được thực hiện thông qua Flask-login.
|
### Thiết lập dự án
|
||||||
|
|
||||||
```
|
#### Frontend
|
||||||
[api/]
|
|
||||||
├── constants // Các cài đặt hằng số được sử dụng trong toàn bộ codebase.
|
|
||||||
├── controllers // Định nghĩa các route API và logic xử lý yêu cầu.
|
|
||||||
├── core // Điều phối ứng dụng cốt lõi, tích hợp mô hình và công cụ.
|
|
||||||
├── docker // Cấu hình liên quan đến Docker & containerization.
|
|
||||||
├── events // Xử lý và xử lý sự kiện
|
|
||||||
├── extensions // Mở rộng với các framework/nền tảng bên thứ 3.
|
|
||||||
├── fields // Định nghĩa trường cho serialization/marshalling.
|
|
||||||
├── libs // Thư viện và tiện ích có thể tái sử dụng.
|
|
||||||
├── migrations // Script cho việc di chuyển cơ sở dữ liệu.
|
|
||||||
├── models // Mô hình cơ sở dữ liệu & định nghĩa schema.
|
|
||||||
├── services // Xác định logic nghiệp vụ.
|
|
||||||
├── storage // Lưu trữ khóa riêng tư.
|
|
||||||
├── tasks // Xử lý các tác vụ bất đồng bộ và công việc nền.
|
|
||||||
└── tests
|
|
||||||
```
|
|
||||||
|
|
||||||
### Frontend
|
Để thiết lập dịch vụ frontend, vui lòng tham khảo [hướng dẫn](https://github.com/langgenius/dify/blob/main/web/README.md) chi tiết của chúng tôi trong file `web/README.md`. Tài liệu này cung cấp hướng dẫn chi tiết để giúp bạn thiết lập môi trường frontend một cách đúng đắn.
|
||||||
|
|
||||||
Website được khởi tạo trên boilerplate [Next.js](https://nextjs.org/) bằng Typescript và sử dụng [Tailwind CSS](https://tailwindcss.com/) cho styling. [React-i18next](https://react.i18next.com/) được sử dụng cho việc quốc tế hóa.
|
#### Backend
|
||||||
|
|
||||||
```
|
Để thiết lập dịch vụ backend, vui lòng tham khảo [hướng dẫn](https://github.com/langgenius/dify/blob/main/api/README.md) chi tiết của chúng tôi trong file `api/README.md`. Tài liệu này chứa hướng dẫn từng bước để giúp bạn khởi chạy backend một cách suôn sẻ.
|
||||||
[web/]
|
|
||||||
├── app // layouts, pages và components
|
|
||||||
│ ├── (commonLayout) // layout chung được sử dụng trong toàn bộ ứng dụng
|
|
||||||
│ ├── (shareLayout) // layouts được chia sẻ cụ thể cho các phiên dựa trên token
|
|
||||||
│ ├── activate // trang kích hoạt
|
|
||||||
│ ├── components // được chia sẻ bởi các trang và layouts
|
|
||||||
│ ├── install // trang cài đặt
|
|
||||||
│ ├── signin // trang đăng nhập
|
|
||||||
│ └── styles // styles được chia sẻ toàn cục
|
|
||||||
├── assets // Tài nguyên tĩnh
|
|
||||||
├── bin // scripts chạy ở bước build
|
|
||||||
├── config // cài đặt và tùy chọn có thể điều chỉnh
|
|
||||||
├── context // contexts được chia sẻ bởi các phần khác nhau của ứng dụng
|
|
||||||
├── dictionaries // File dịch cho từng ngôn ngữ
|
|
||||||
├── docker // cấu hình container
|
|
||||||
├── hooks // Hooks có thể tái sử dụng
|
|
||||||
├── i18n // Cấu hình quốc tế hóa
|
|
||||||
├── models // mô tả các mô hình dữ liệu & hình dạng của phản hồi API
|
|
||||||
├── public // tài nguyên meta như favicon
|
|
||||||
├── service // xác định hình dạng của các hành động API
|
|
||||||
├── test
|
|
||||||
├── types // mô tả các tham số hàm và giá trị trả về
|
|
||||||
└── utils // Các hàm tiện ích được chia sẻ
|
|
||||||
```
|
|
||||||
|
|
||||||
## Gửi PR của bạn
|
#### Các điểm cần lưu ý khác
|
||||||
|
|
||||||
Cuối cùng, đã đến lúc mở một pull request (PR) đến repository của chúng tôi. Đối với các tính năng lớn, chúng tôi sẽ merge chúng vào nhánh `deploy/dev` để kiểm tra trước khi đưa vào nhánh `main`. Nếu bạn gặp vấn đề như xung đột merge hoặc không biết cách mở pull request, hãy xem [hướng dẫn về pull request của GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests).
|
Chúng tôi khuyến nghị xem xét kỹ tài liệu này trước khi tiến hành thiết lập, vì nó chứa thông tin thiết yếu về:
|
||||||
|
- Điều kiện tiên quyết và dependencies
|
||||||
|
- Các bước cài đặt
|
||||||
|
- Chi tiết cấu hình
|
||||||
|
- Các mẹo xử lý sự cố phổ biến
|
||||||
|
|
||||||
Và thế là xong! Khi PR của bạn được merge, bạn sẽ được giới thiệu là một người đóng góp trong [README](https://github.com/langgenius/dify/blob/main/README.md) của chúng tôi.
|
Đừng ngần ngại liên hệ nếu bạn gặp bất kỳ vấn đề nào trong quá trình thiết lập.
|
||||||
|
|
||||||
## Nhận trợ giúp
|
## Nhận trợ giúp
|
||||||
|
|
||||||
Nếu bạn gặp khó khăn hoặc có câu hỏi cấp bách trong quá trình đóng góp, hãy đặt câu hỏi của bạn trong vấn đề GitHub liên quan, hoặc tham gia [Discord](https://discord.gg/8Tpq4AcN9c) của chúng tôi để trò chuyện nhanh chóng.
|
Nếu bạn bị mắc kẹt hoặc có câu hỏi cấp bách trong quá trình đóng góp, chỉ cần gửi câu hỏi của bạn thông qua issue GitHub liên quan, hoặc tham gia [Discord](https://discord.gg/8Tpq4AcN9c) của chúng tôi để trò chuyện nhanh.
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue