이득:
- LLM API 요청의 기본 구조(엔드포인트, 모델, 메시지, max_tokens)를 설명할 수 있습니다.
- 시스템, 사용자, 보조 역할과 상태 비저장 대화 기록 간의 차이점을 이해합니다.
- 반환된 응답의 필드(콘텐츠 차단, stop_reason, 사용법)를 읽고 해석할 수 있습니다.
이전 모듈에서는 채팅창에서 인공지능을 사용했습니다. 그러나 자신의 제품, 자동화 또는 워크플로에 AI를 포함시키려는 경우 채팅 인터페이스로는 충분하지 않습니다. 프로그래밍 방식으로, 즉 코드나 자동화 도구를 사용하여 모델에 연결해야 합니다. 이 브리지의 이름은 API(Application Programing Interface, 두 소프트웨어가 특정 규칙에 따라 통신할 수 있도록 하는 계약)입니다. 이 단원을 마치면 LLM(Large Language Model) API 요청의 구성 요소, 메시지 역할의 역할, 응답을 읽는 방법을 알게 됩니다. 이는 모듈의 나머지 부분이 구축될 기반입니다.
API는 어떻게 작동하나요?
API의 기본 흐름은 다음과 같습니다. 특정 형식으로 요청을 보냅니다. 서버는 특정 형식으로 응답을 반환합니다. LLM에서 이는 일반적으로 단일 주소(엔드포인트, 요청을 처리하는 서버의 고정 주소)에 대한 HTTP 호출(HTTP: 웹에서 요청-응답을 전달하기 위한 표준 프로토콜)입니다. 예를 들어 메시징 API에서 모든 요청은 단일 주소로 이동하며 본문에서 JSON(JavaScript Object Notation - 사람과 기계가 모두 읽을 수 있는 키/값 쌍으로 구성된 텍스트 형식)으로 전달됩니다.
요청에서는 최소한 다음 세 가지를 지정합니다.
- 모델: 사용할 모델(예: 빠르고 저렴한 모델 또는 강력한 모델)
- max_tokens: 모델이 생성할 수 있는 최대 토큰 수(텍스트가 처리되는 가장 작은 단위, 다음 단위에서 자세히 처리됩니다). 즉, 출력 제한.
- 메시지: 대화를 구성하는 메시지 목록입니다.
단계별: 요청 설정 방법
- 엔드포인트와 자격 증명을 준비합니다. 헤더의 요청에 API 키(신원을 증명하는 비밀 문자열)를 추가합니다. 코드에 키를 삽입하면 안 됩니다. 9호실의 안전한 보관에 대해 다루겠습니다.
- 모델과 출력 제한을 선택하세요. 간단한 작업을 위한 경량 모델 + 작은 max_tokens; 강력한 모델 + 복잡한 작업에 대한 더 큰 한계.
- 메시지 목록을 설정합니다. List the system instruction, user message, and past rounds (if any).
- 요청을 보내고 응답을 구문 분석합니다. 반환된 JSON에서 텍스트 콘텐츠, 중지 이유, 토큰 사용량을 읽습니다.
메시지 역할: 시스템, 사용자, 보조자
대화는 순서대로 배열된 메시지로 구성되며 각 메시지에는 역할이 있습니다. 역할은 모델이 해당 텍스트를 처리하는 방법을 결정합니다.
역할
글을 쓰는 사람
목적
시스템
개발자/운영자
전체 대화에 적용되는 영구적인 지침, 성격 및 규칙
사용자
최종 사용자
사용자의 현재 질문 또는 입력
조수
모델
모델에 의해 생성된 응답(및 이전 응답)
시스템 역할은 대부분의 공급자 요청 본문에서 별도의 시스템 필드로 제공됩니다. 사용자와 보조자는 메시지 목록에 순차적으로 나열됩니다. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "귀하는 기업 지원 보조원입니다. 짧고 형식적이며 확인된 답변을 제공하십시오. 확실하지 않은 정보를 구성하지 마십시오.", "messages": [ { "role": "user", "content": "반품 절차를 어떻게 시작합니까?" } ]}
말은 무국적이다
가장 일반적인 오해는 다음과 같습니다. LLM API 호출은 상태 비저장입니다. 즉, 서버는 두 요청 사이에 메모리를 유지하지 않습니다. 모델이 이전 요청을 기억하지 않습니다. 다중 라운드 채팅을 설정하는 경우 새로운 요청이 있을 때마다 지난 라운드를 다시 보내야 합니다. 모델의 "메모리"는 귀하가 보낸 메시지 목록으로 구성됩니다.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "안녕하세요, 제 이름은 데니즈입니다." }, { "role": "도우미", "content": "안녕 데니즈, 무엇을 도와드릴까요?" }, { "role": "user", "content": "방금 내 이름을 말했어요. 기억하시나요?" } ]}
세 번째 메시지에 올바르게 응답하려면 이전 메시지를 모두 보내야 합니다. 보내지 않으시면 모델이 "바다"를 인식하지 못하고 오답을 하게 됩니다. 이는 비용에도 직접적인 영향을 미칩니다. 대화가 길어질수록 목록이 커지고 각 요청이 더 많은 토큰을 소비합니다.
팁: 긴 대화에서 전체 기록을 보내는 대신 이전 라운드(요약 + 마지막 몇 라운드)를 요약하고 이동하면 비용이 절감되고 컨텍스트 창이 보존됩니다. 이 내용은 6단원과 11단원에서 자세히 설명하겠습니다.
답변 읽기
모델이 응답을 반환하면 일반 텍스트가 아닌 구조화된 개체를 받게 됩니다. 전형적인 지역:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "반품을 시작하려면 계정의 '내 주문' 페이지로 이동하세요..." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 47, "output_tokens": 88 }}
- 내용: 응답 자체입니다. 콘텐츠 블록 목록입니다. 텍스트 블록의 텍스트 필드가 실제 답변입니다.
- stop_reason: 모델이 중지된 이유입니다. end_turn = 자연 종료; max_tokens = 출력 제한에 멈췄습니다(응답이 불완전할 수 있음). 거절 = 보안상의 이유로 거절되었습니다. 코드에서는 항상 stop_reason을 먼저 확인해야 합니다.
- 사용법: 토큰 번호를 입력 및 출력합니다. 이는 비용 및 한도 추적의 기초입니다.
주의: stop_reason이 max_tokens이면 응답이 완료되지 않습니다. 이를 "성공적인 응답"으로 간주하고 사용자에게 텍스트의 절반만 표시하는 것은 제작 과정에서 가장 흔히 저지르는 실수 중 하나입니다. max_tokens를 늘리거나 스트리밍을 사용하세요.
약한 프롬프트 / 강한 프롬프트
두 개의 서로 다른 시스템 프롬프트를 사용한 동일한 작업:
# WEAK당신은 조수입니다. 질문에 답하십시오.
# STRONG당신은 기업 지원 보조원입니다. 규칙:- 제공된 정책 문서의 정보에만 의존하십시오. 문서에 없는 경우에는 "이 정보가 없습니다. 관련 부서에 전달하겠습니다."라고 말씀해 주세요. - 답변은 3문장을 넘지 않아야 하며, 형식적이고 명확해야 합니다. - 개인정보(TC ID번호, 카드번호)를 묻거나 반복하지 마세요. - 확실하지 않을 때는 추측하지 마세요.
강력한 버전; 이는 범위, 형식, 안전 여유 및 불확실성의 동작을 정의합니다. 모델 출력의 일관성은 이러한 명확성에서 직접적으로 비롯됩니다.
미니 케이스 3개
사례 1 — 지원 봇(무상태 트랩). 전자상거래 팀이 봇을 실시간으로 공개했습니다. 사용자가 "이전 주문 취소"라고 말하면 봇이 주문 번호를 "잊어버렸습니다". 이유: 마지막 메시지만 포함하여 각 요청을 보내고 있었습니다. 해결 방법: 메시지 목록에 마지막 6라운드를 추가했습니다. 결과: 컨텍스트는 유지되지만 요청당 입력이 40개 토큰에서 최대 600개 토큰으로 증가했습니다. 비용 교훈은 단원 2에서 다루겠습니다.
사례 2 — 불완전한 계약 요약. 법무팀은 10페이지 분량의 계약서를 작성하고 있었습니다. max_tokens: 300이 낮게 유지되었으며 요약이 문장 중간에서 잘렸습니다. stop_reason은 매번 max_tokens였지만 아무도 보고 있지 않았습니다. max_tokens를 1500으로 늘리고 stop_reason 확인을 추가했습니다. 잘린 요약 비율이 18%에서 0%로 감소했습니다.
사례 3 — 역할 혼합. 마케팅 팀은 사용자 메시지에 모든 지침을 작성하고 시스템을 비워 두었습니다. 사용자 입력과 명령이 혼합되면 모델은 "이전 규칙을 잊어버리세요"라는 사용자 명령을 따르는 경우가 있습니다. 그들은 영구 규칙을 시스템으로 옮겼습니다. 사용자 입력과 명령을 분리함으로써 규칙 위반이 크게 감소했습니다.
일반적인 실수
- 과거를 보내는 것을 잊음: 모델은 "기억하지 못한다"고 생각됩니다. 반면에 무국적자입니다. 당신은 맥락을 가지고 있습니다.
- `stop_reason`을 확인하지 않음: max_tokens로 중지된 응답은 완료된 것으로 간주됩니다.
- `user`에 명령 삽입: 시스템에 지속적인 규칙; 즉각적인 입력이 사용자에게 전달됩니다. 혼합하면 보안 취약점이 발생합니다.
- 'content'를 일반 문자열로 착각: 답은 블록 목록입니다. 첫 번째 텍스트 블록의 텍스트 필드를 읽고, 블라인드 인덱스를 사용하여 content[0]을 가져오기 전에 해당 유형을 확인하세요.
- 코드에 키 삽입: 환경 변수를 사용합니다(단위 9).
심층: 콘텐츠 블록 및 여러 부분으로 구성된 답변
응답의 콘텐츠 필드가 목록인 이유를 이해하는 것은 나중에 접하게 될 고급 기능의 기본입니다. 때때로 모델은 단일 텍스트 블록이 아니라 여러 블록을 반환합니다. 즉, 사고 블록과 텍스트 블록이 뒤따릅니다. 또는 도구 사용 블록이 뒤따르는 텍스트 블록입니다. 이것이 바로 content[0]를 "답변"으로 맹목적으로 계산하는 것이 취약한 이유입니다. 올바른 접근 방식은 목록을 살펴보고 유형별로 정렬하는 것입니다. 유형 필드가 텍스트인 블록의 텍스트 콘텐츠를 수집하고 다른 유형(사고, 도구)을 별도로 처리합니다.
실제로 이러한 구별이 하는 일은 사용자에게 공개하지 않고 모델의 추론(있는 경우)을 기록하고, 도구 호출을 별도의 로직으로 리디렉션하고, 실제 답변만 화면에 인쇄할 수 있다는 것입니다. 모듈이 진행됨에 따라(특히 단원 4와 11에서) 이 블록 구조가 출력을 검증하고 지시하는 데 얼마나 유용한지 알게 될 것입니다.
또 다른 실용적인 점은 다양한 제공자 플랫폼(클라우드 제공자를 통한 직접 API)에서 동일한 모델에 액세스할 수 있다는 것입니다. 엔드포인트 주소와 인증 형식은 변경될 수 있지만 메시지 역할, 상태 비저장, 응답 구조와 같은 기본 개념은 동일하게 유지됩니다. 따라서 이 단원의 기본 사항은 사용하는 플랫폼에 관계없이 적용됩니다.
요약하면
LLM API 요청은 모델, 출력 제한 및 메시지 목록으로 구성됩니다. 역할(시스템, 사용자, 보조자)이 모델의 동작을 결정합니다. 호출은 상태 비저장입니다. 각 요청마다 컨텍스트를 전달합니다. 응답은 구조화된 객체입니다. 내용, stop_reason 및 사용 필드를 읽고 해석하는 것은 생산 내구성의 기초입니다.
응용과제
자신의 직업에 맞는 작업을 선택하세요(예: 수신 이메일 정렬, 간략한 요약 작성). 종이에: (1) 4-5개의 규칙으로 시스템 프롬프트를 작성하고, (2) 샘플 사용자 메시지와 2라운드 내역을 설정하고, (3) max_tokens에 대한 합리적인 값을 결정하고 근거를 작성하고, (4) 반환된 응답에서 처리할 stop_reason 값과 방법을 나열합니다.
체크리스트
- [ ] 요청의 세 가지 필수 부분(모델, max_tokens, 메시지)을 셀 수 있습니다.
- [ ] 시스템, 사용자, 보조자 역할의 차이점을 설명할 수 있습니다.
- [ ] 통화는 무국적이며 과거를 전달해야 한다는 것을 알고 있습니다.
- [ ] 콘텐츠, stop_reason 및 사용 필드를 읽고 댓글을 달 수 있습니다.
- [ ] max_tokens를 사용하면 잘린 응답을 확인하고 처리할 수 있습니다.