Dify 참고 자료 SKILL
구문, API, CLI 등 참고 정보 검색
빠른 탐색
DSL 구문 참고
워크플로우 DSL 구조
version: 0.0.1
graph:
nodes:
- id: node_id
data:
type: node_type
# 노드 구성
edges:
- source: source_node_id
target: target_node_id
노드 유형
| 유형 | 설명 | 필드 |
|---|---|---|
start | 시작 노드 | variables |
llm | LLM 노드 | model, prompt_template |
agent | Agent 노드 | agent_parameters |
knowledge-retrieval | 지식 검색 | dataset_ids, query_variable_selector |
http-request | HTTP 요청 | url, method, headers |
code | 코드 실행 | code_type, code |
tool | 도구 노드 | provider_type, tool_name |
if-else | 조건 분기 | conditions |
iteration | 반복 | iterator_variable_name |
loop | 루프 | max_loop_count |
answer | 응답 노드 | answer |
변수 참조
# 시스템 변수
{{#sys.query#}} # 사용자 쿼리
{{#sys.files#}} # 업로드된 파일
{{#sys.conversation_id#}} # 대화 ID
# 노드 출력
{{#node_id.output_field#}}
# 배열 접근
{{#items[0]#}} # 배열 첫 번째 요소
{{#items[-1]#}} # 배열 마지막 요소
# 객체 속성
{{#object.field#}} # 객체 속성
전체 예제
workflow:
graph:
nodes:
- id: start
data:
type: start
variables:
- name: query
type: text
required: true
- id: classify
data:
type: question-classifier
instruction: "사용자 질문 분류"
categories:
- name: technical
description: 기술 질문
- name: general
description: 일반 질문
- id: llm
data:
type: llm
model:
provider: openai
name: gpt-4
prompt_template:
- role: system
text: "당신은 도우미입니다"
- role: user
text: "{{#start.query#}}"
context:
enabled: false
- id: answer
data:
type: answer
answer: "{{#llm.text#}}"
edges:
- source: start
target: classify
- source: classify
target: llm
source_handle: general
- source: llm
target: answer
API 참고
인증
모든 API 요청은 Header에 API Key를 포함해야 합니다:
Authorization: Bearer YOUR_API_KEY
엔드포인트 개요
애플리케이션 API
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/chat-messages | POST | 채팅 메시지 전송 |
/v1/completions | POST | 텍스트 완성 |
/v1/parameters | GET | 애플리케이션 매개변수 가져오기 |
/v1/file-upload | POST | 파일 업로드 |
워크플로우 API
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/workflows/run | POST | 워크플로우 실행 |
/v1/workflows/run | GET | 실행 상태 가져오기 |
/v1/workflows/tasks | GET | 작업 목록 가져오기 |
데이터셋 API
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/datasets | GET | 데이터셋 목록 |
/v1/datasets | POST | 데이터셋 생성 |
/v1/datasets/{id}/documents | GET | 문서 목록 |
/v1/datasets/{id}/retrieve | POST | 지식 검색 |
요청/응답 형식
채팅 메시지 요청
{
"query": "사용자 쿼리",
"user": "user_123",
"conversation_id": "선택적 대화 ID",
"response_mode": "blocking | streaming",
"files": [
{
"type": "image",
"transfer_method": "remote_url",
"url": "https://example.com/image.jpg"
}
],
"retrieval_model": {
"query": "{{#sys.query#}}",
"top_k": 3
}
}
채팅 메시지 응답
{
"message_id": "msg_xxx",
"conversation_id": "conv_xxx",
"answer": "AI 응답 내용",
"metadata": {
"usage": {
"prompt_tokens": 100,
"completion_tokens": 50,
"total_tokens": 150
},
"retrieval_resources": [
{
"position": 1,
"document_id": "doc_xxx",
"content": "관련 문서 내용..."
}
]
}
}
오류 응답
{
"code": "invalid_api_key",
"message": "Invalid API key",
"status_code": 401
}
일반 오류 코드:
| 오류 코드 | HTTP 상태 코드 | 설명 |
|---|---|---|
invalid_api_key | 401 | API Key가 유효하지 않음 |
invalid_parameter | 400 | 매개변수 오류 |
quota_exceeded | 403 | 할당량 초과 |
rate_limit_exceeded | 429 | 속도 제한 초과 |
internal_server_error | 500 | 서버 오류 |
SDK 참고
Python SDK
설치
pip install dify-client
기본 사용법
from dify_client import DifyClient
# 클라이언트 초기화
client = DifyClient(
api_key="app-xxx",
base_url="https://api.dify.ai/v1"
)
# 채팅 메시지 전송
response = client.chat.messages.create(
query="안녕하세요",
user="user_123"
)
print(response.answer)
스트리밍 응답
from dify_client import DifyClient
client = DifyClient(api_key="app-xxx")
# 스트리밍 채팅
for event in client.chat.messages.stream(
query="이야기 해줘",
user="user_123"
):
if event.event == "message":
print(event.data.answer, end="")
워크플로우 실행
# 워크플로우 실행
response = client.workflows.run(
inputs={"query": "테스트"},
user="user_123",
response_mode="blocking"
)
print(response.data.output)
SDK 클래스 참고
DifyClient
class DifyClient:
def __init__(self, api_key: str, base_url: str = "https://api.dify.ai/v1"):
"""클라이언트 초기화"""
pass
@property
def chat(self) -> ChatClient:
"""채팅 클라이언트"""
pass
@property
def workflows(self) -> WorkflowClient:
"""워크플로우 클라이언트"""
pass
@property
def datasets(self) -> DatasetClient:
"""데이터셋 클라이언트"""
pass
ChatClient
class ChatClient:
def create(self, query: str, user: str, **kwargs) -> ChatMessage:
"""채팅 메시지 전송 (블로킹)"""
pass
def stream(self, query: str, user: str, **kwargs) -> Iterator[ChatEvent]:
"""채팅 메시지 전송 (스트리밍)"""
pass
CLI 참고
설치
pip install dify-cli
명령어 개요
플러그인 명령어
# 플러그인 초기화
dify plugin init [options]
# 플러그인 실행
dify plugin run [options]
# 플러그인 패키징
dify plugin package [options]
# 플러그인 게시
dify plugin publish [options]
# 설치된 플러그인 목록
dify plugin list
워크플로우 명령어
# 워크플로우 내보내기
dify workflow export <workflow_id> [options]
# 워크플로우 가져오기
dify workflow import <file> [options]
# 워크플로우 검증
dify workflow validate <file>
# 워크플로우 실행
dify workflow run <workflow_id> --inputs '{}'
애플리케이션 명령어
# 애플리케이션 목록
dify app list
# 애플리케이션 정보 가져오기
dify app info <app_id>
# 애플리케이션 배포
dify app deploy <app_id>
환경 변수 명령어
# 환경 변수 목록
dify env list
# 환경 변수 설정
dify env set <key> <value>
# 환경 변수 가져오기
dify env get <key>
# 환경 변수 삭제
dify env delete <key>
옵션 설명
| 옵션 | 약어 | 설명 | 기본값 |
|---|---|---|---|
--api-key | -k | API Key | 환경 변수 DIFY_API_KEY |
--base-url | -b | 기본 URL | https://api.dify.ai/v1 |
--output | -o | 출력 형식 | json |
--quiet | -q | 조용한 모드 | false |
--debug | -d | 디버그 모드 | false |
사용 예제
# API Key 설정
export DIFY_API_KEY="app-xxx"
# 플러그인 프로젝트 초기화
dify plugin init my-plugin --template tool
# 플러그인 실행
dify plugin run --port 5000
# 워크플로우 내보내기
dify workflow export wf_xxx -o workflow.yaml
# 워크플로우 가져오기
dify workflow import workflow.yaml
자주 묻는 질문
API 관련
Q: API Key는 어떻게 얻나요? A: Dify 콘솔 -> 설정 -> API에서 생성합니다.
Q: 요청 빈도 제한은 얼마인가요? A: 기본 60 요청/분이며, 상향 요청할 수 있습니다.
Q: 스트리밍 응답을 어떻게 처리하나요?
A: response_mode=streaming을 사용하고 SSE 이벤트를 파싱합니다.
워크플로우 관련
Q: 변수를 어떻게 참조하나요?
A: {{#node_id.field#}} 구문을 사용합니다.
Q: 어떤 노드 유형을 지원하나요? A: 자세한 내용은 노드 유형 표를 참조하세요.
Q: 루프를 어떻게 처리하나요?
A: iteration 또는 loop 노드를 사용합니다.
플러그인 관련
Q: 커스텀 플러그인을 어떻게 개발하나요? A: 02-plugin SKILL을 참조하세요.
Q: 플러그인이 자격 증명을 어떻게 가져오나요?
A: self.runtime_credentials를 사용합니다.
관련 SKILL
- 01-workflow - 워크플로우 설계
- 02-plugin - 플러그인 개발
- 05-integration - 통합 확장
관련 리소스
버전 정보: v1.0.0 | 마지막 업데이트: 2026-03-05