노드 추가 및 연결
워크플로우를 구성하는 노드를 추가하고 데이터 흐름을 연결하는 방법을 설명합니다.
노드 추가 방법
1. 퀵 추가 (Quick Add)
[Screenshot] 노드 추가 (Quick Add 패널)
왼쪽 패널의 Quick Add 섹션에서 원하는 유형의 노드를 캔버스로 드래그 앤 드롭합니다.
2. 컬렉션에서 가져오기
왼쪽 패널의 Collections 트리에서 이미 만들어둔 데이터셋이나 코드를 찾아 드래그 앤 드롭합니다. 재사용성을 높이는 가장 좋은 방법입니다.
3. 컨텍스트 메뉴
캔버스 빈 공간을 우클릭하여 메뉴를 열고, Add Dataset 또는 Add Code를 선택합니다.
노드 위에서 우클릭하면 다음 옵션을 사용할 수 있습니다:
| 메뉴 항목 | 설명 |
|---|---|
| Edit Node | 노드 편집 (Inspector 열기) |
| Duplicate Node | 노드 복제 |
| Add Result Dataset | AI가 자동으로 출력 데이터셋 노드를 생성하여 연결 |
| Save As | 참조 중인 코드 노드를 편집하면 현재 파이프라인 전용 복사본으로 분기 저장 (아래 참조) |
| Delete Node | 노드 삭제 |
코드 노드 참조와 Save-As 모델
코드 노드는 컬렉션에 저장된 공용 코드 자산을 파이프라인에서 참조하는 방식으로 동작합니다. 동일한 코드를 여러 파이프라인에서 재사용할 수 있으며, 편집 시에는 다음 Save-As 규칙이 적용됩니다(ADR-0006).
- 파이프라인에서 참조 코드 노드를 연 뒤 내용을 수정하면, 화면 상단에 읽기 전용 경고와 함께 Save As 버튼이 표시됩니다.
- Save As를 누르면 현재 파이프라인 안쪽에 동일한 로직의 복사본 코드 노드가 생성되고, 이후 편집은 이 복사본에만 영향을 줍니다.
- 원본 코드 자산은 그대로 유지되어 다른 파이프라인에 영향을 주지 않습니다.
이 모델은 이전의 "Reference + Fork-on-Edit" 방식을 대체합니다. 즉, 자동 분기를 만들지 않고 사용자가 명시적으로 분기 시점을 결정합니다.
4. 키보드 단축키
빠른 작업을 위해 다음 단축키를 사용할 수 있습니다.
- 데이터셋 노드 추가:
Ctrl(Cmd) + Shift + D - 코드 노드 추가:
Ctrl(Cmd) + Shift + C
노드 유형
데이터셋 노드 (Dataset Node)
데이터의 소스(Source) 또는 싱크(Sink) 역할을 합니다. 데이터셋의 서브타입(type)에 따라 노드가 자동으로 적절한 어댑터를 사용합니다.
| 서브타입 | 설명 | 용도 |
|---|---|---|
delta | Delta Lake 테이블 | 배치 데이터 처리, 버전 관리 |
kafka | Kafka 토픽 | 실시간 스트리밍 데이터 |
rest | HTTP 엔드포인트 | 외부 API 호출 |
object | 파일/객체 스토리지 | 비정형 파일 입출력 |
Delta Lake 노드 설정
- 테이블 이름: Delta Lake 테이블 경로
- 스키마: 컬럼 정의 (자동 추론 가능)
- 파티션 키: 데이터 분할 기준 컬럼
- 쓰기 모드: Append, Overwrite, Merge
Kafka 노드 설정
- 토픽: Kafka 토픽 이름
- 브로커: Kafka 브로커 주소
- 직렬화 포맷: JSON, Avro, Protobuf
- Consumer Group: (소스 노드인 경우)
코드 노드 (Code Node)
데이터를 변환하거나 처리하는 로직을 수행합니다.
| 타입 | 언어 | 용도 |
|---|---|---|
| Python | Python 3.x | 범용 데이터 처리, ML 모델 적용 |
| SQL | SQL | 데이터 변환, 집계, 조인 |
Python 노드 설정
- 스크립트: Python 코드 작성
- 패키지 의존성: 필요한 pip 패키지 목록
- 입력 변수: 입력 데이터셋 매핑
- 출력 변수: 출력 데이터셋 매핑
import pandas as pd
df = input_dataset.read()
df['total'] = df['price'] * df['quantity']
df = df[df['total'] > 1000]
output_dataset.write(df)
SQL 노드 설정
- 쿼리: SQL 쿼리 작성
- 입력 테이블 별칭: 입력 데이터셋을 테이블로 참조
- 출력 스키마: 결과 스키마 정의
SELECT
category,
SUM(amount) as total_amount,
COUNT(*) as order_count
FROM orders
WHERE order_date >= '2024-01-01'
GROUP BY category
ORDER BY total_amount DESC
Entity / Relation 노드 (온톨로지 자원)
온톨로지로 정의된 EntityType과 RelationType도 step의 입출력으로 사용할 수 있습니다(ADR-0059 / Manager ADR-0059).
캔버스에 Entity / Relation 노드가 배치된 상태. Inspector에 Identity Keys / Display Column / backing dataset 링크가 보여야 합니다. PK 누락 경고도 함께 보여주면 좋습니다.
- PK 필수: 엔티티/관계는 Identity Keys(PK)가 정의되어 있어야 합니다. PK가 비어 있으면 편집기에 노란 경고가 표시되고, 실행 시 페이로드 생성이 거부됩니다.
- backing dataset 자동 매핑: 노드는 EntityType/RelationType이 가리키는 backing dataset에 자동으로 연결됩니다. Inspector의 Schema 탭에서 매핑된 컬럼·키를 확인할 수 있습니다.
- Display Column: UI 표면에서 인스턴스를 1차 라벨로 식별할 컬럼. 파이프라인 실행 로그·인스펙터 미리보기에서도 사용됩니다.
HITL 노드 (Human-in-the-Loop)
워크플로우 중간에 사람의 승인을 받아야 하는 단계입니다. 실행이 HITL 노드에 도달하면, 미리 지정된 채팅 표면(예: Knowledge Chat, Agent Chat)에 승인 요청이 게시되고 응답을 받기 전까지 다음 단계로 진행하지 않습니다(ADR-0035 / ADR-0038).
HITL 노드가 캔버스에 배치되고, Inspector에서 승인 표면·승인자 그룹·승인 요청 페이로드 스키마를 설정하는 화면.
- 승인 표면: 어느 채팅 표면(에이전트 채팅, 지식 채팅 등)으로 승인 요청을 보낼지 지정합니다.
- 승인자 그룹: 승인할 수 있는 사용자/그룹.
- 승인 페이로드 스키마: 채팅에 함께 노출될 입력 페이로드의 스키마. 승인자가 맥락을 파악하는 데 사용됩니다.
- 타임아웃 / 거부 처리: 일정 시간 내 응답이 없거나 거부되면 파이프라인은 실패 상태로 마감되고 트레이스가 기록됩니다.
노드 연결
데이터의 흐름을 정의하기 위해 노드들을 연결합니다.
- 선행 노드(Upstream)의 오른쪽 핸들(Output)에 마우스를 가져갑니다.
- 클릭 후 드래그하여 후행 노드(Downstream)의 왼쪽 핸들(Input)에 놓습니다.
- 연결선(Edge)이 생성되며 데이터 의존성이 설정됩니다.
연결 규칙
- 데이터셋 / Entity / Relation 노드 → 코드 노드: 데이터 읽기 (소스)
- 코드 노드 → 데이터셋 / Entity / Relation 노드: 데이터 쓰기 (싱크)
- 코드 노드 → 코드 노드: 중간 결과 전달
- 임의 노드 → HITL 노드 → 임의 노드: 사람 승인 게이트
코드 노드와 데이터셋 노드를 연결하면, 코드 내의 입출력 변수가 데이터셋 ID와 자동으로 매핑될 수 있습니다. (Inspector의 Options 탭에서 확인 가능)
노드 관리
- 이동: 노드를 드래그하여 위치를 변경합니다.
- 복제: 노드를 선택하고 우클릭 메뉴의 Duplicate Node를 선택하거나
Ctrl+D를 사용합니다. - 삭제: 노드를 선택하고
Delete키를 누르거나 우클릭 메뉴의 Delete Node를 선택합니다. - 자동 정렬: 툴바의 Auto Layout 드롭다운에서 6가지 레이아웃 알고리즘을 선택할 수 있습니다:
| 레이아웃 | 설명 |
|---|---|
| LR | Left-to-Right (좌→우 방향) |
| TB | Top-to-Bottom (상→하 방향) |
| DAG | 방향성 비순환 그래프 레이아웃 |
| Force | 힘 기반 자동 정렬 |
| Circular | 원형 배치 |
| Grid | 격자형 배치 |
- 그룹 선택:
Shift+ 드래그로 여러 노드를 한 번에 선택합니다.