코딩 없이 쓰는 LG 엑사원 2.5, API 키 발급부터 첫 질문까지

API 키를 발급받고 접속 주소와 모델 식별자를 지정하면 복잡한 프로그래밍 코드를 직접 작성하지 않고도 K-EXAONE 2.5에 질의할 수 있다. 이번 실습에서는 오픈소스 기반 데스크톱 도구인 챗박스(Chatbox) 웹 앱과 간결한 파이썬(Python) 스크립트로 동일한 행사 공지문을 전달해 실제 모델의 응답 결과까지 단계별로 확인했다.

이번 실습의 핵심 목표는 개인정보가 배제된 실무 문안에서 핵심 일정과 준비물을 정확히 추출해내는 실전 연결이다. 고객용 상용 서비스를 배포하는 개발 단계가 아니며, 이용약관에 명시된 비상업적 연구·학습 권한을 전제로 진행한다.

공식 플랫폼 회원가입과 30일 실습용 API 키 발급

플랫폼 개요 가이드에 안내된 EXAONE API Platform 첫 화면에서 로그인 메뉴를 선택한다. 계정이 없을 경우 회원가입 창에서 이메일 인증 절차를 거쳐 신규 계정을 생성할 수 있다. 이용약관에 따라 플랫폼 이용 자격은 만 19세 이상으로 제한된다.

로그인을 마친 뒤 ‘API Key 발급하기’를 누르면 키 관리 대시보드로 이동한다. ‘API Key 생성하기’를 클릭해 식별용 이름을 입력하고 생성을 확정하는 순서다. 이름은 나중에 용도를 쉽게 알아볼 수 있도록 ‘공지문 실습용’처럼 구체적으로 정한다.

생성 직후 나타나는 안내 팝업에서 복사(Copy)를 눌러 안전한 곳에 저장해야 한다. 화면 경고문대로 생성된 비밀 키 문자열은 최초 1회만 화면에 노출되며 창을 닫으면 다시 확인할 수 없다. 분실 시 키를 삭제하고 재발급받아야 하므로, 비밀번호 관리자나 로컬 보안 메모장에 즉시 옮겨 적는다.

키를 복사해 두는 행위와 실제 질문을 서버로 전송하는 과정은 별개의 단계다. 이용약관상 발급된 API 키의 유효기간은 30일로 고정돼 있어 기한이 지나면 자동으로 비활성화된다. 공식 인증 문서는 발급된 키를 외부에 공유하거나 깃허브 등 공개 저장소 코드에 직접 적지 말라고 명시한다. 키는 질문 본문이나 웹 게시판에 붙여넣지 않고 연결 프로그램의 전용 환경변수 설정란에만 입력해야 한다.

서드파티 채팅 도구 챗박스의 구조와 활용 목적

챗박스 공식 사이트에서 제공하는 챗박스는 여러 AI 모델을 단일한 채팅 인터페이스에서 구동할 수 있도록 돕는 서드파티 데스크톱 및 웹 클라이언트 앱이다. LG가 운영하는 공식 포털과는 별개의 독립 오픈소스 기반 도구다. 독자가 채팅창에 질문을 입력하면, 챗박스가 등록된 엔드포인트 주소를 통해 LG 서버로 질의를 전송하고 가공된 결과를 받아 화면에 띄워주는 방식으로 작동한다. 여러 가전기기를 하나의 리모컨으로 조작하듯, 단일한 채팅창에서 외부 AI 모델을 손쉽게 호출하는 구조다.

이번 실습에서 챗박스를 선택한 이유는 터미널 코딩 지식이 없는 비개발자 독자도 클릭 몇 번으로 API 연동을 직관적으로 체감할 수 있기 때문이다. 공급자 연동 가이드에 정리된 대로 별도 프로그램 설치 없이 웹 브라우저에서 곧바로 실행할 수 있으며, 사용자 지정 엔드포인트 주소와 API 키를 입력해 신규 모델을 추가할 수 있다. 물론 필수 도구는 아니므로 뒤에서 다룰 파이썬 스크립트나 다른 호환 클라이언트를 자유롭게 선택해도 무방하다.

챗박스는 공식 서비스 사양과 같이 자체 유료 AI 구독 서비스와 외부 API 키 연동 기능을 병행 제공한다. 이번 실습에서 이용하는 것은 순수하게 본인의 LG API 키를 연결하는 기능이며, 챗박스 자체 모델을 유료 구독하는 절차가 아니다. 외부 앱의 로컬 스토리지에 키를 보관하는 방식이므로 공용 PC에서는 사용 후 설정을 초기화하는 주의가 필요하다.

개발자 중심의 환경이라면 에이전트 시작 문서에 안내된 오픈코드(OpenCode)나 헤르메스(Hermes) 같은 코딩 에이전트 도구를 활용할 수도 있다. API 접속 주소(`https://api.exaone.ai/v1`)와 모델 식별자(`k-exaone_v2.5`)를 에디터 설정에 등록해 소스 코드 리팩토링이나 버그 수정을 요청하는 경로다. 이번 실습에서는 진입 장벽이 낮은 챗박스를 중심으로 절차를 전개하며 코딩 도구는 공식 가이드를 바탕으로 한 대안 경로로 제시한다.

오픈AI 호환 규격 기반 챗박스 연결 설정

한국어 웹 화면 기준으로 상단 ‘설정’, ‘모델 공급자’, ‘추가’, ‘사용자 지정 공급자 추가’ 순서로 메뉴를 이동한다. 공급자 이름에는 ‘EXAONE’을 적고 API 모드는 반드시 ‘오픈AI(OpenAI) API 호환’을 선택한다. 자체 유료 구독 모델과 혼선이 생기지 않도록 사용자 지정 공급자를 독립적으로 생성하는 과정이다.

API 스펙 문서에 명시된 LG 공식 요청 경로는 `https://api.exaone.ai/v1/chat/completions`다. 호스트와 경로를 분리 입력한 뒤 챗박스 하단의 미리보기 URL이 공식 주소와 정확히 일치하는지 대조한다. 툴 버전에 따라 주소 입력 방식이 다를 수 있으나 최종 결합 주소에 `/v1`이 중복되지 않도록 확인하는 것이 핵심이다.

모델 목록에서 ‘신규’를 눌러 식별자인 `k-exaone_v2.5`를 수동으로 등록한다. 이번 실습에서는 문맥 창에 `524288`, 최대 출력 토큰(Max Tokens)에 `4096`을 입력했다. 스펙 명세대로 입력과 출력 토큰의 합산치가 52만4288토큰을 초과하면 400 에러가 반환되므로 무리하게 출력값을 늘릴 필요는 없다.

설정창을 닫은 뒤 첫 질의 전송 시 브라우저 보안 정책에 따라 ‘Network Error: Failed to fetch’ 오류가 발생할 수 있다. 이 경우 공급자 설정 화면에서 ‘네트워크 호환성 개선’ 옵션을 활성화하면 브라우저의 교차 출처 리소스 공유(CORS) 프록시를 거쳐 정상 통신이 이뤄진다. 정상 접속 환경이라면 해당 옵션을 강제로 켤 필요는 없다.

설정을 마친 뒤 새 대화창의 상단 드롭다운 메뉴에서 등록한 EXAONE 모델을 선택하고, 아래 준비된 실습용 텍스트를 복사해 입력창에 전송한다. 키는 설정창에만 입력하고 본문에는 넣지 않아야 한다.

다음 실습용 공지에서 일시·대상·준비물·장소를 추출해줘.
원문에 없는 항목은 '기재 없음'으로 적어줘.
11월 20일 오후 2시, 성인 대상 무료 독서 모임을 연다.
참가자는 읽고 싶은 책 한 권을 준비한다.

위 문안은 파싱 절차를 테스트하기 위해 구성한 가상 안내문이다. 일시, 대상, 준비물이 원문 문맥과 정확히 일치하는지 확인하고, 특히 공지문에 언급되지 않은 ‘장소’ 항목에 대해 모델이 없는 정보를 지어내지 않고 ‘기재 없음’으로 처리하는지 살피는 것이 검증의 핵심이다.

실제 질의 결과 K-EXAONE 2.5는 일시(’11월 20일 오후 2시’), 대상(‘성인’), 준비물(‘읽고 싶은 책 한 권’)을 정확히 추려냈으며, 장소 항목에는 요구대로 ‘기재 없음’이라는 명확한 답을 돌려줬다. 상단 모델 식별자가 `k-exaone_v2.5`로 유지된 상태에서 무코딩 요청과 파싱 응답이 단절 없이 완성된 것이다. 브라우저 캐시를 삭제하면 웹 앱 설정이 지워질 수 있으므로 발급받은 키는 개인 보관함에 별도로 저장해 둔다.

파이썬 표준 라이브러리를 활용한 API 직접 호출 실습

구글 코랩 FAQ에 소개된 코랩은 별도 파이썬 환경 구축 없이 웹 브라우저에서 대화형으로 코드를 실행할 수 있는 클라우드 플랫폼이다. 구글 코랩 환경에 로그인해 새 노트북을 생성하고 코드 셀에 아래 스크립트를 붙여넣으면 로컬 고성능 GPU 없이도 클라우드 상에서 API를 직접 호출할 수 있다.

실행 버튼을 누르면 API 키 입력창이 활성화된다. 파이썬 공식 문서에 기술된 getpass 모듈은 은행 ATM에서 비밀번호를 입력할 때 화면에 숫자가 보이지 않듯, 터미널 화면에 비밀 키 문자를 표시하지 않고 안전하게 입력받는 표준 보안 함수다. 노트북 코드를 타인과 공유할 때 소스 코드나 결과 출력창에 민감한 키가 노출되는 사고를 원천 방지할 수 있다.

import json
from getpass import getpass
from urllib.request import Request, urlopen
from urllib.error import HTTPError, URLError
key = getpass("EXAONE API 키: ").strip()
prompt = """다음 실습용 공지에서 일시·대상·준비물·장소를 추출해줘.
원문에 없는 항목은 '기재 없음'으로 적어줘.
11월 20일 오후 2시, 성인 대상 무료 독서 모임을 연다.
참가자는 읽고 싶은 책 한 권을 준비한다."""
payload = {
    "model": "k-exaone_v2.5",
    "messages": [{"role": "user", "content": prompt}],
    "reasoning_effort": "low",
    "max_tokens": 4096,
    "stream": False,
}
if not key:
    print("API 키를 입력한 뒤 다시 실행한다.")
else:
    request = Request(
        "https://api.exaone.ai/v1/chat/completions",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {key}",
            "Content-Type": "application/json",
        },
        method="POST",
    )
    try:
        with urlopen(request, timeout=120) as response:
            result = json.loads(response.read())
        answer = result["choices"][0]["message"].get("content")
        print(
            answer
            or "최종 답변이 비어 있다. 출력 한도를 확인한다."
        )
    except HTTPError as error:
        print(
            f"요청 실패: HTTP {error.code}. 오류 안내를 확인한다."
        )
    except (URLError, TimeoutError):
        print("네트워크 연결 또는 응답 대기 시간을 확인한다.")
    except (
        ValueError,
        KeyError,
        IndexError,
        TypeError,
        AttributeError,
    ):
        print(
            "예상한 응답 형식이 아니다. 공식 API 문서를 확인한다."
        )

코드에서 변경할 부분은 `prompt` 변수 내부의 질의 문안이며, `model`에는 호출할 식별자인 `k-exaone_v2.5`를 전달한다. API 스펙 문서에 명시된 대로 모델은 추론(Thinking) 과정과 최종 답변(Content)을 분리 반환한다. 위 예제는 사용자가 읽을 최종 답변인 `content` 필드만 선별 출력하도록 작성돼 내부 추론 텍스트의 파싱 번거로움을 덜었다.

11월 10일 윈도우(Windows) 환경의 파이썬 3.13 버전에서 테스트를 수행한 결과, 콘솔창에 일시, 대상, 준비물 항목이 깔끔하게 정돈되어 출력됐고 장소는 ‘기재 없음’으로 정확히 식별됐다. 한 건의 질의 성공은 시스템 간 통신 엔드포인트가 정상적으로 열려 있음을 증명하는 최소한의 기능 검증이다.

출력 결과 대조와 오류 코드 대응 수칙

공지문에 없는 엉뚱한 연도나 임의의 장소가 답변에 덧붙여졌다면, 문맥이 아무리 자연스럽더라도 텍스트 정보 추출에는 실패한 것이다. 모델의 답변을 맹신하지 않고 생성된 결과물을 원본 문안과 1:1로 대조하는 습관이 실무 도입의 기본 전제다.

“답변이 그럴듯하게 흘러나왔다고 실습이 끝난 것은 아니다. 원문에 없는 날짜나 장소를 지어내지 않았는지 대조하는 작업이 사실 확인의 출발점이다.”

요청 실패 시 반환되는 에러 코드는 공식 에러 코드 문서를 통해 즉시 원인을 진단할 수 있다. 401은 API 키 오타나 30일 유효기간 만료가 원인이며, 429는 분당 호출 한도를 초과했을 때 발생하므로 잠시 대기한 뒤 재시도해야 한다. 400은 문맥 한도 초과 등 페이로드 형식 결함, 500은 서버 내부 장애를 뜻한다. 호출 한도 가이드에서 밝힌 잔여 호출 쿼터는 응답 HTTP 헤더(`x-ratelimit`)를 통해 실시간 확인할 수 있다.

프롬프트 데이터의 학습 활용 여부는 개인정보처리방침에서 규정한 선택 동의 항목이다. 비상업적 학습 실습이라 하더라도 타인의 연락처나 주민등록번호 등 민감 정보가 포함된 사내 문서는 테스트 데이터에서 전면 배제해야 한다. 실습을 마친 뒤에는 클립보드에 남아 있는 API 키를 비워두는 보안 관리를 잊지 말아야 한다.