결과만 보면 실패 지점을 찾을 수 없다
예약 확인 서비스를 예로 들어 봅시다. 사용자가 “내일 3시에 가능한가요?”라고 묻고 잠시 뒤 오류 화면을 보았습니다. 질문이 모델에 도착하지 않았는지, 모델이 예약 시스템에 잘못 요청했는지, 예약 시스템은 답했지만 시간 제한 안에 서비스가 받지 못했는지 결과만으로는 구분할 수 없습니다. 시퀀스 다이어그램은 각 참여자의 생명선과 그 사이 메시지를 시간순으로 그려, 관찰 가능한 사건을 복원합니다. 이것은 시스템의 내부 사고를 그린 그림이 아니라 외부에서 정의하거나 기록할 수 있는 통신 순서입니다.[1]
참여자, 생명선, 메시지, 활성 구간을 구별한다
맨 위 상자는 참여자입니다. 사용자처럼 사람일 수도 있고 웹 화면, LLM 서비스, 검색 도구, 데이터베이스 같은 시스템일 수도 있습니다. 아래로 이어지는 점선은 그 참여자가 시간 속에 존재함을 나타내는 생명선입니다. 가로 화살표는 메시지이며, 화살표 위에는 ‘검색해 줘’ 같은 의도가 아니라 API 호출명·입력·응답처럼 관찰할 수 있는 내용을 적습니다. 좁은 세로 막대인 활성 구간은 작업을 수행하는 시간입니다. 위에 있는 메시지가 먼저이고 아래에 있는 메시지가 나중입니다.
문장마다 보내는 쪽, 받는 쪽, 내용을 적는다
“사용자가 예약 시간을 묻는다. 서비스는 예약 API를 조회한다. 빈 시간이 있으면 후보를 보여 주고, 없으면 다른 날짜를 요청한다”라는 원문을 메시지 표로 바꿉니다. 보내는 쪽과 받는 쪽을 먼저 확정한 다음, 입력값과 응답값을 적습니다. ‘조회한다’만 적지 말고 날짜·시간대·자원 식별자가 포함되는지 확인합니다. 실패 응답도 정상 응답과 같은 수준으로 기록합니다. 응답이 없는 경우는 빈 화살표가 아니라 시간 초과 사건과 사용자 안내라는 별도 메시지로 표시해야 합니다.
| 보내는 쪽 → 받는 쪽 | 메시지 | 가능한 응답 |
|---|---|---|
| 사용자 → 화면 | 날짜·시간 요청 | 입력 접수 |
| 서비스 → 예약 API | availability(date,time) | 가능 / 없음 / 오류 |
| 서비스 → 사용자 | 조회 결과 설명 | 선택 또는 날짜 변경 |
검색을 쓰는 LLM 답변의 정상 순서를 그린다
검색을 사용하는 답변에서는 모델이 모든 자료를 알고 있다고 그려서는 안 됩니다. 사용자의 질문을 받은 오케스트레이터가 검색 요청을 만들고, 검색 도구가 문서 목록과 위치를 반환하며, 그 자료를 포함한 문맥으로 모델에 생성 요청을 보냅니다. 모델은 답변 초안을 돌려주고, 서비스는 출처 링크와 형식을 점검한 뒤 사용자에게 전달합니다. 실제 제품에 따라 참여자와 순서는 달라질 수 있으므로 이 도표는 교육용 시스템 예시라고 밝혀야 합니다. 특히 모델이 검색 도구를 직접 실행한다고 단정하지 않고 어느 구성 요소가 호출을 담당하는지 구분합니다.
시간 초과 뒤에는 같은 요청을 무조건 반복하지 않는다
도구가 늦게 응답하면 서비스는 시간 초과를 기록하고 사용자에게 현재 상태를 알려야 합니다. 재시도를 할 때는 같은 작업이 두 번 실행되어도 문제가 없는지 확인합니다. 읽기 전용 검색은 다시 시도하기 쉽지만 예약 확정이나 결제처럼 상태를 바꾸는 요청은 중복 식별자 없이 재시도하면 두 번 처리될 수 있습니다. 시퀀스 도표에는 ‘timeout 3초’, ‘retry 1회’, ‘같은 request-id 사용’, ‘최종 실패 안내’를 명시합니다. 실패 구간을 정상 흐름 아래에 작게 붙이는 대신 같은 중요도로 그려야 운영 규칙이 보입니다.
참여자와 관찰 가능한 메시지만 요구한다
LLM에 시퀀스 다이어그램을 요청할 때는 시스템 구성 요소와 경계를 알려 줍니다. “AI가 생각한다”처럼 측정할 수 없는 내부 과정을 메시지로 만들지 말고, 화면 요청·API 호출·결과·오류 코드처럼 기록 가능한 사건을 적게 합니다. 정상, 빈 결과, 시간 초과의 세 경로를 각각 출력하게 하면 행복 경로만 그리는 오류를 줄일 수 있습니다. 실제 로그가 있다면 시간표시와 request-id를 익명화해 제공하고, 없으면 예시임을 표시합니다.
다음 예약 확인 절차를 시퀀스 다이어그램 초안으로 바꿔 주세요. 참여자: 사용자 / 웹 화면 / LLM 서비스 / 예약 API. 목적: 메시지의 시간 순서와 실패 응답을 확인한다. 정상 흐름: 사용자가 날짜와 시간을 입력하고, 서비스가 예약 API를 조회해 가능한 시간을 설명한다. 대안 흐름: 빈 결과면 다른 날짜를 요청한다. 실패 흐름: 3초 안에 응답이 없으면 같은 request-id로 읽기 요청을 한 번만 재시도하고, 다시 실패하면 사용자에게 지연을 알린다. 규칙: 모든 화살표에 보내는 값 또는 응답을 적는다. 모델 내부 사고는 그리지 않는다. 출력: ① 메시지 표 ② Mermaid sequenceDiagram ③ 누락된 오류 처리 질문.
답이 먼저 도착하는 시간 역전을 찾는다
LLM이 만든 도표에서 흔한 오류는 검색 결과보다 답변 생성이 먼저 놓이는 것입니다. 도구 결과를 답변 근거로 쓴다면 결과 수신 뒤에 생성 요청이 와야 합니다. 또 하나는 실패 응답의 수신자가 사라지는 오류입니다. 예약 API의 500 오류를 서비스가 받았는데 사용자에게 성공 답을 보내면 모순입니다. 마지막으로 ‘alt’ 조건이 겹칠 수 있습니다. [빈 결과]와 [API 오류]를 같은 가지로 묶으면 사용자 안내와 재시도 정책을 구분할 수 없습니다. 메시지 표와 도표를 위에서 아래로 한 줄씩 대조하면 이런 오류가 보입니다.
② 답변 생성
③ 검색 결과 수신
아직 받지 않은 자료를 답에 사용합니다.
② 검색 결과 수신
③ 결과를 포함해 생성 요청
④ 답변 전달
스윔레인은 책임, 시퀀스는 한 사례의 시간순서를 묻는다
스윔레인도 왼쪽에서 오른쪽 흐름을 보여 주지만 주된 질문은 누가 맡는가입니다. 시퀀스 다이어그램은 특정 요청 한 건이 어떤 메시지를 차례로 주고받는지 묻습니다. 한 참여자가 같은 시간대에 여러 요청을 처리하는 전체 업무량은 시퀀스 한 장으로 판단하기 어렵습니다. 또한 세로 간격이 실제 초 단위를 뜻하지 않는 경우가 많습니다. 실제 지연 시간을 분석하려면 로그의 타임스탬프나 다음 부에서 다룰 실행 시간표를 함께 사용해야 합니다.
| 구분 | 스윔레인 | 시퀀스 |
|---|---|---|
| 중심 질문 | 누가 맡는가? | 무엇이 먼저 오가는가? |
| 기본 단위 | 역할 안의 작업 | 참여자 사이 메시지 |
| 강점 | 책임·인계 누락 | 시간 역전·실패 응답 |
| 주의 | 정확한 시간 표현은 약함 | 전체 책임 체계는 복잡해짐 |
메시지를 한 단계씩 재생하며 모순을 찾자
시나리오를 고른 뒤 다음 메시지 버튼을 눌러 보세요. 정상 흐름, 빈 결과, 시간 초과는 같은 질문에서 시작하지만 중간 이후 메시지가 달라집니다. 각 단계에서 다음 수신자가 무엇을 알아야 하는지 먼저 예상해 보십시오. 이 실습은 실제 네트워크를 호출하지 않고 미리 정한 메시지 목록을 재생합니다.