Tài liệu

Dify

Dify truy cập endpoint bên ngoài thông qua một plugin — OpenAI-API-compatible — và một trường bắt buộc, URL cơ sở API. Điền trường này và mọi nút LLM trong quy trình làm việc của bạn đều có thể gọi các id Claude và GPT bằng một khóa duy nhất.

Một trường bắt buộc — API Base URL trong biểu mẫu Add Model của plugin tương thích OpenAI API — trỏ mọi nút LLM trong workspace Dify tới Kunavo.

Nhà cung cấp mô hình → Tương thích OpenAI-API → Thêm mô hình

# Integrations → Model Provider → OpenAI-API-compatible → Add Model
Type                          LLM
Model Name                    claude-sonnet-5
Model display name            Kunavo · Claude Sonnet 5
API Key                       sk-kn-...
API Base URL                  https://api.kunavo.com/v1
model name for API endpoint   (leave blank — Model Name is already the id)
Completion mode               Chat
Model context size            1000000
Upper bound for max tokens    (your own ceiling for one reply)
Function Call Type            Tool Call     # defaults to no_call
Vision Support                Support       # only if you will send images
Structured Output             Support       # defaults to not supported

# Model context size is per model, not per endpoint: 1000000 is
# claude-sonnet-5's. The table below carries the rest.

URL cơ sở API giữ nguyên /v1. Plugin khai báo endpoint_url dưới nhãn API Base URL, đánh dấu đây là trường bắt buộc duy nhất ngoài tên mô hình và đặt văn bản gợi ý “URL cơ sở, ví dụ: https://api.openai.com/v1” — văn bản gợi ý đó là câu xác định cách điền biểu mẫu. README của chính plugin giải thích trường hợp ngoại lệ thay vì mâu thuẫn với điều này: với các loại mô hình không phải LLM, plugin “tự nối phiên bản API ở bên trong”, nên các loại đó dùng địa chỉ gốc không kèm đường dẫn để tránh lặp /v1/v1. Không có mô hình Kunavo nào thuộc các loại đó, nên dạng /v1 là dạng duy nhất bạn cần.

Ba công tắc mặc định đều tắt, và đây là lỗi thường gặp. Function Call Type mặc định là no_call, còn Structured Output và Vision Support là không hỗ trợ. Một mô hình được thêm với các giá trị mặc định sẽ trả lời hoàn hảo trong một nút chat thông thường, rồi thất bại trong nút Agent hoặc quy trình làm việc có sử dụng công cụ — trông giống như lỗi endpoint nhưng thực ra không phải. Hãy đặt các giá trị này khi thêm mô hình, trước khi gỡ lỗi bất cứ điều gì khác.

Kunavo không cung cấp mô hình embedding, mô hình chuyển văn bản thành giọng nói hay mô hình chuyển giọng nói thành văn bản, và cũng không cung cấp chức năng xếp hạng lại — vì vậy mục nhà cung cấp này chỉ áp dụng cho vị trí LLM của Dify, không dùng cho mục đích nào khác. Cơ sở tri thức được lập chỉ mục ở chế độ High Quality, URL Rerank Endpoint hoặc nút giọng nói vẫn giữ nhà cung cấp hiện có; trỏ một nút LLM đến đây không chuyển các lệnh gọi đó sang Kunavo.

Cấu hình này được đối chiếu với danh sách plugin và lược đồ nhà cung cấp của chính Dify vào ngày bên dưới. Kunavo chưa chạy một không gian làm việc Dify với endpoint của mình — chưa thêm mô hình vào không gian làm việc đang hoạt động, chưa thực thi quy trình làm việc, chưa có lượt trao đổi công cụ dạng truyền phát. Trang hướng dẫn thiết lập đã xuất bản không đồng nghĩa với việc đã kiểm thử. Phần curl bên dưới là điều bạn có thể xác minh trong mười giây; mọi việc sau đó đều phụ thuộc vào bạn và Dify.

Chưa có khóa? Tạo tài khoản Kunavo, tạo khóa (bắt đầu bằng sk-kn-) và nạp tín dụng từ $10 — các lệnh gọi được thanh toán từ số dư đó và các lệnh gọi thất bại không bị tính phí. Sau đó, bảng điều khiển mở tại phần thiết lập Dify.

Từng bước

Tạo khóa tại /app/keys rồi sao chép khóa — khóa chỉ hiển thị một lần.
Trong Dify, mở Tích hợp → Nhà cung cấp mô hình, duyệt Cài đặt nhà cung cấp mô hình (hoặc Marketplace) rồi cài đặt Tương thích với OpenAI API, do langgenius phát hành. Tài liệu Dify lưu ý rằng chỉ chủ sở hữu không gian làm việc và quản trị viên mới có thể quản lý nhà cung cấp.
Nhấp Thêm mô hình trên thẻ của nhà cung cấp đó. Plugin không có mô hình được xác định sẵn — đây là nhà cung cấp customizable-model — vì vậy mỗi ID bạn muốn dùng cần được thêm thành một mục riêng.
Điền biểu mẫu như trên. Loại = LLM, Tên mô hình = chính xác ID của Kunavo, Khóa API = khóa sk-kn- của bạn, URL cơ sở API = https://api.kunavo.com/v1, Chế độ hoàn tất = Chat, và Kích thước ngữ cảnh mô hình theo bảng bên dưới. Sau đó đặt Loại lệnh gọi hàm, cùng Đầu ra có cấu trúc và Hỗ trợ hình ảnh nếu bạn cần. Lưu lại.
Mở một quy trình làm việc và chọn mô hình trên nút cần sử dụng nó — Dify gán mô hình theo từng nút, không phải theo từng ứng dụng, nên nút phân loại và nút tạo nội dung cuối có thể dùng các ID và mức giá khác nhau. Ứng dụng và nút không chọn mô hình nào sẽ dùng Mô hình mặc định → Mô hình suy luận hệ thống.
Chạy một quy trình làm việc có phạm vi giới hạn, rồi xem khoản phí trong tài khoản Kunavo của bạn thay vì trong Dify — xem ghi chú về cách hiển thị chi phí bên dưới.

Đã kiểm tra đối chiếu với Trang plugin Tương thích với OpenAI API của Dify vào 21 tháng 9, 2026. Cài đặt của bên thứ ba có thể thay đổi; nếu tên trường ở đây không còn khớp với những gì bạn thấy, trang đó là nguồn có thẩm quyền, không phải trang này.

Đây là phiên bản ngắn. Hướng dẫn đầy đủ — lựa chọn mô hình, chi phí của một phiên thực tế và các trường hợp lỗi — nằm trong hướng dẫn từng bước về chi phí trong Dify.

Xác minh trước khi gỡ lỗi ứng dụng khách

Một yêu cầu sẽ xác định liệu lỗi nằm ở endpoint, khóa hay tệp cấu hình. Nếu lệnh này trả về JSON, cùng base URL và khóa sẽ hoạt động trong Dify.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Đặt model id nào vào trường

Mọi mô hình văn bản đều có thể truy cập bằng model id — danh sách đang hoạt động là GET /v1/models, còn danh mục kèm giá nằm trên trang mô hình. Mức giá tính bằng USD trên mỗi 1M token, đầu vào / đầu ra.

ID mô hình	Kunavo vào / ra	Phù hợp ở đâu trong Dify
`claude-sonnet-5`	$1.40 / $7.00	mô hình đang hoạt động cho các nút tạo nội dung và agent — kích thước ngữ cảnh 1000000
`claude-opus-5`	$3.50 / $17.50	nút có đầu ra mà con người đọc, hoặc một kế hoạch mà nếu sai sẽ rất tốn kém — 1000000
`claude-haiku-4-5`	$0.70 / $3.50	các nút phân loại, định tuyến và trích xuất, nơi thực sự tập trung khối lượng lệnh gọi — 200000
`gpt-5-6-sol`	$2.00 / $12.00	một họ mô hình thứ hai dùng cùng khóa, dưới dạng mục mô hình riêng — 1050000
`gpt-5-6-terra`	$0.70 / $4.20	các nút xử lý tài liệu dài — 1050000

Thanh toán theo token từ số dư trả trước, không có phí hàng tháng — xem trang Thanh toán. Với ngữ cảnh lặp lại — chiếm phần lớn dữ liệu mà trình chỉnh sửa hoặc ứng dụng trò chuyện gửi đi — bộ nhớ đệm prompt ảnh hưởng đến hóa đơn nhiều hơn lựa chọn mô hình.

Có hai thứ khác nhau được gọi là “API Dify”

Trang này nói về một trong số đó, còn kết quả tìm kiếm thường xuyên trộn lẫn cả hai.

Đưa một mô hình vào Dify — đây là việc khối thiết lập bên trên thực hiện. Dify là ứng dụng khách, Kunavo là endpoint, còn thông tin xác thực bạn dán vào là khóa sk-kn-. Khi đó, mọi nút LLM trong mọi ứng dụng thuộc không gian làm việc đó đều có thể gọi các ID bạn đã thêm.
Gọi một ứng dụng Dify từ mã của bạn — đây là Service API mà Dify cung cấp cho ứng dụng đã xuất bản, cùng khóa app- riêng do Dify cấp. Đó là khóa của Dify, không phải của chúng tôi, và bạn không thể trỏ khóa đó đến nơi khác. Kunavo không tham gia vào hướng kết nối này.

Hai hướng này có thể chạy đồng thời trên cùng một ứng dụng, và thường là như vậy: backend của bạn gọi ứng dụng Dify bằng khóa Dify, còn các nút trong ứng dụng gọi Kunavo bằng khóa Kunavo. Hai khóa, hai hóa đơn, hai nơi cần kiểm tra khi gặp lỗi 401.

Vì sao Dify không hiển thị chi phí cho mô hình bạn đã thêm

Các tệp mô hình được xác định sẵn của bên thứ nhất trong Dify có khối giá — mức giá đầu vào và đầu ra cùng đơn vị tính theo token — và Dify nhân số token của bạn với mức giá đó để hiển thị con số trong nhật ký. Lược đồ nhà cung cấp Tương thích với OpenAI API không khai báo trường giá, đơn vị hay tiền tệ nào, theo kết quả kiểm tra vào ngày nêu trên. Vì vậy, với mô hình được thêm qua plugin này, Dify không có mức giá để nhân, và cột tiền không phải là khoản giảm giá bạn vừa tìm thấy hay lỗi bạn gây ra: đó là trường dữ liệu không tồn tại. Hãy xem số tiền thực tế trong mức sử dụng Kunavo của bạn, và coi số token của Dify là số token.

Có một công tắc liên quan nên để nguyên: Đưa thông tin mức sử dụng vào luồng được bật theo mặc định và yêu cầu endpoint cung cấp số token của lời nhắc và phần hoàn tất trong khối dữ liệu cuối cùng của luồng. Tắt công tắc này đồng nghĩa với việc bạn cũng mất các số liệu token.

Nếu bạn tự lưu trữ Dify

Ngăn xếp Docker Compose định tuyến các yêu cầu đi ra ngoài qua dịch vụ ssrf_proxy, vì vậy endpoint phải truy cập được từ bên trong mạng container — chứ không chỉ từ trình duyệt trên máy tính xách tay của bạn. Cấu hình hoạt động ở nơi này nhưng hết thời gian chờ ở nơi kia thường là do vấn đề đó; đây là vấn đề mạng, không phải thông tin xác thực. Lệnh curl ở trên, chạy từ bên trong container, sẽ trả lời trực tiếp câu hỏi này.

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

Làm cách nào để kết nối API tùy chỉnh tương thích với OpenAI với Dify?

Cài plugin Tương thích với OpenAI API do langgenius phát hành từ Tích hợp → Nhà cung cấp mô hình → Cài đặt nhà cung cấp mô hình hoặc Dify Marketplace. Nhấp Thêm mô hình trên thẻ của plugin rồi điền biểu mẫu: Loại, Tên mô hình, Tên hiển thị mô hình, Khóa API, URL cơ sở API, Chế độ hoàn tất và Kích thước ngữ cảnh mô hình, cùng các công tắc tính năng. Nhà cung cấp này không có mô hình được xác định sẵn — đây là nhà cung cấp mô hình tùy chỉnh, vì vậy mỗi ID mô hình bạn muốn dùng cần có một mục riêng, và mỗi mục có URL cơ sở cùng khóa riêng.

URL cơ sở API của Dify có cần kết thúc bằng /v1 không?

Có, với mô hình chat. Lược đồ nhà cung cấp của plugin đặt tên trường là URL cơ sở API, đánh dấu trường này là bắt buộc và đưa ra gợi ý "Base URL, e.g. https://api.openai.com/v1", nên đường dẫn gốc /v1 là định dạng được tài liệu hướng dẫn — với Kunavo, hãy dùng https://api.kunavo.com/v1. Chỉ với các loại mô hình mà plugin tự thêm phiên bản API thì tài liệu mới hướng dẫn dùng phần gốc trần; nếu không, đường dẫn sẽ có /v1/v1 bị lặp. Kunavo không cung cấp mô hình thuộc các loại đó, nên hãy dùng định dạng có /v1. Thiếu /v1 sẽ gây lỗi 404 chứ không phải lỗi xác thực.

Vì sao nút Agent của Dify không thể dùng công cụ với mô hình tôi đã thêm?

Vì Loại lệnh gọi hàm mặc định là no_call đối với mô hình được thêm qua plugin Tương thích với OpenAI API, còn Đầu ra có cấu trúc, Hỗ trợ hình ảnh, Gọi hàm qua luồng và Hỗ trợ Chế độ suy nghĩ đều mặc định là không hỗ trợ. Đây là các khai báo mà Dify tin theo chứ không phải kết quả thăm dò, nên một mô hình có đủ khả năng nhưng được thêm với các giá trị mặc định vẫn sẽ bị nút Agent hoặc nút có sử dụng công cụ từ chối. Mở cấu hình mô hình và đặt Loại lệnh gọi hàm thành Tool Call — Function Call là dạng cũ hơn — rồi kiểm tra lại trước khi cho rằng endpoint có lỗi.

Vì sao Dify không hiển thị giá cho mô hình được thêm qua plugin tương thích?

Vì lược đồ nhà cung cấp của plugin đó hoàn toàn không có trường giá, trong khi các tệp mô hình được xác định sẵn của bên thứ nhất trong Dify lại có. Do đó, Dify không có mức giá theo token để nhân với số token của bạn và không hiển thị gì thay vì đưa ra ước tính. Hãy lấy số tiền từ hồ sơ sử dụng của chính nhà cung cấp và coi số liệu của Dify là số token. Để Đưa thông tin mức sử dụng vào luồng bật là cách giữ cho số liệu token tiếp tục được gửi đến.

Thêm Kunavo vào Dify có giống với việc cung cấp ứng dụng Dify dưới dạng API không?

Không, hai hướng hoạt động ngược nhau. Thêm Kunavo khiến Dify trở thành ứng dụng khách: các nút của Dify gửi yêu cầu đến endpoint bạn đã cấu hình bằng khóa Kunavo. Service API của Dify khiến mã của bạn trở thành ứng dụng khách: mã gọi ứng dụng Dify đã xuất bản bằng khóa do Dify cấp, và không có URL cơ sở nào của chúng tôi được dùng trong đường dẫn đó. Một ứng dụng thường thực hiện cả hai việc cùng lúc, vì vậy khi gặp lỗi 401, trước tiên nên xác định cụ thể khóa nào gây ra lỗi.

Kunavo đã kiểm thử cấu hình này trong Dify chưa?

Chưa. Những gì được kiểm tra vào ngày 21 tháng 9 năm 2026 là tài liệu của chính Dify — mục giới thiệu plugin trên Dify Marketplace và lược đồ nhà cung cấp trong kho plugin chính thức của Dify; đây là nguồn của các tên trường, thứ tự của chúng, cờ bắt buộc và giá trị mặc định được nêu ở đây. Chưa ai thêm mô hình Kunavo vào một không gian làm việc Dify đang hoạt động rồi chạy quy trình làm việc qua mô hình đó, vì vậy không có tuyên bố nào về việc truyền phát, các lượt gọi công cụ và nhận kết quả hay các vòng lặp agent chạy lâu trong ứng dụng khách này. Điều duy nhất bạn có thể xác minh riêng là endpoint và khóa có hoạt động hay không; lệnh curl trên trang này thực hiện việc kiểm tra đó.