공식 문서도 2차 출처도 틀렸습니다 — API 검증에서 다섯 번 뒤집힌 기록

사내 문서 지식그래프 검색 도구에서 회의 녹취를 글로 옮기는 부분이 있습니다. 한 대형 모델 제공사가 새 음성인식 모델을 내면서 가격 인하와 화자 분리를 함께 내세웠고, 운영 중인 경로와 같은 녹취로 대 보기로 했습니다. 정확도와 시간과 비용을 재는 일 자체는 반나절이면 끝날 계획이었습니다.

그런데 실측에 도달하기까지의 길목에서 다섯 번 걸렸습니다. 콘솔 가입, 파일 업로드 경로 선택, 중개 판매처 조사, 결제 등록, 키 발급. 전부 문서를 읽고 결론을 내는 종류의 일이었고, 다섯 번 다 읽은 것이 틀렸습니다. 그리고 다섯 번 다 뒤집는 데 1분 안팎이 들었습니다.

카드 없이 무료 사용량을 받는다는 글

첫 번째는 가입 조건이었습니다. 여러 소개 글이 결제 수단 등록 없이 무료 사용량을 받을 수 있다고 적고 있었습니다. 실제로는 콘솔이 결제 수단 없음으로 막았습니다. 등록 전에는 모든 모델의 무료분이 0 으로 보였고, 가입을 마무리하는 단계 자체가 결제 수단 등록이었습니다.

카드를 넣고 나서야 대상 모델에 100만 토큰 90일이라는 무료분이 들어왔습니다. 소개 글이 거짓말을 했다기보다 그 글을 쓴 시점의 조건이 지금과 달랐을 가능성이 큽니다. 요금과 가입 조건은 2차 출처에서 가장 빨리 낡는 항목입니다. 그 한 줄로 일정이나 예산을 세우면 세운 직후부터 틀립니다.

공식 문서가 안 된다고 적어 둔 것

두 번째가 가장 비쌌을 뻔한 자리입니다. 공식 문서에 임시 파일 업로드는 특정 리전 전용이라고 적혀 있었습니다. 우리 작업 공간은 그 리전이 아니었습니다. 문서대로라면 객체 저장소를 따로 개설하고 접근 권한을 붙이고 업로드 경로를 새로 짜야 했습니다. 실측 한 번 해 보려고 인프라가 한 덩어리 늘어나는 셈이었습니다.

그 견적을 적기 직전에 그냥 한 번 쳐 봤습니다. 다른 리전에서 그대로 성공했습니다. 걸린 시간은 요청 한 번, 1분이 안 됐습니다.

공식 문서는 되는 것보다 안 되는 것을 더 자주 틀립니다. 제약이 먼저 풀리고 문서가 늦게 따라오기 때문입니다. 문서에서 제약 문장을 만났을 때 그래서 못 한다로 바로 넘어가면, 풀려 있는 제약을 근거로 우회로를 짓게 됩니다. 문서를 믿지 말라는 뜻이 아니라 결론을 적기 직전에 한 번 만져 보라는 뜻입니다.

200 이 왔다고 그 모델이 있는 것은 아닙니다

세 번째는 중개 판매 플랫폼 조사였습니다. 그 모델을 더 싸게 파는 곳이 있는지 보려고 세 곳을 봤습니다. 처음에는 모델 주소로 요청을 보내 상태 코드를 보는 방식으로 확인했습니다. 한 곳이 계속 200 을 돌려줘서 취급한다고 판단했습니다.

확신이 안 서서 있지도 않은 가짜 모델명을 하나 만들어 같은 자리에 넣어 봤습니다. 거기에도 200 이 왔습니다. 그 창구는 모델이 있든 없든 200 을 주는 곳이었고, 상태 코드로는 존재 여부를 가릴 수 없었습니다. 나머지 두 곳은 다른 방식으로 확인했는데 한 곳은 음성인식 모델 자체를 취급하지 않았고, 다른 한 곳은 같은 모델을 정가의 두 배에 팔면서 문서에 화자 분리가 없었습니다.

여기서 남은 것은 플랫폼 평가가 아니라 검사 자체에 대한 것입니다. 처음에 고른 검사는 실패할 수 없는 검사였습니다. 모델이 있어도 200, 없어도 200 이면 그 검사는 아무것도 확인하지 않습니다. 가짜 입력 하나를 일부러 넣어 본 덕분에 그 사실이 드러났습니다.

이게 아니라면 무엇이 보일까. 대답이 똑같이 보인다면, 그 검사는 아무것도 확인하지 않습니다.

화면이 멈춘 것은 실패의 근거가 아닙니다

네 번째는 결제 수단 등록 화면이었습니다. 카드 정보를 넣고 제출했는데 화면이 계속 돌기만 했습니다. 새로고침하고 다시 넣고 싶은 손이 먼저 움직입니다. 그런데 결제 등록은 되돌리기 번거로운 행위입니다. 중복으로 시도하면 등록이 둘 생기거나 카드사 쪽에 승인 시도가 두 번 남습니다.

다시 누르기 전에 됐는지부터 세 군데를 봤습니다. 가입 페이지의 단계 표시, 콘솔의 사용 제한 표시, 카드사 알림입니다. 셋 다 등록된 쪽을 가리켰습니다. 멈춰 있던 것은 화면 하나였고 등록은 이미 끝나 있었습니다.

출력이 없는 것, 화면이 멈춘 것, 응답이 안 오는 것은 전부 실패의 근거가 못 됩니다. 되돌릴 수 없는 행위는 재시도 전에 결과부터 확인합니다. 배포, 전송, 결제, 게시가 전부 같은 자리입니다.

가리는 장치가 실제 형식을 모르면 안 가리는 것과 같습니다

다섯 번째는 키 발급이었습니다. 발급받은 API 키를 화면에서 읽어 오는 과정이 있었고, 키 값이 기록에 남지 않도록 가리는 장치를 붙여 뒀습니다. 그 장치는 미리 정해 둔 패턴으로 키를 찾아 별표로 바꾸는 방식이었습니다.

새 제공사의 키 형식이 그 패턴과 달랐습니다. 패턴이 아무것도 못 찾았고, 화면 덤프에 키 원문이 그대로 찍혔습니다. 가리는 장치가 있으니 안전하다고 생각하는 동안 실제로는 아무것도 가려지지 않은 상태였습니다. 그 사실은 덤프를 열어 봐야 알 수 있었습니다. 시험을 마친 뒤 키를 재발급했습니다.

가리는 장치가 붙어 있다는 사실과 그 장치가 지금 이 값을 가린다는 사실은 다른 것입니다. 뒤쪽은 실제 값 하나를 통과시켜 봐야 확인됩니다.

다섯 자리를 한 줄로 늘어놓으면

다섯 번 모두 쳐 본 쪽으로 정했습니다. 객체 저장소는 개설하지 않았고, 중개 플랫폼은 경유하지 않았으며, 결제는 중복으로 시도하지 않았고, 노출된 키는 재발급했습니다. 그 위에서 본래 하려던 실측까지 갔고 결론은 지금은 바꾸지 않는다였습니다.

공통점은 하나입니다. 뒤집는 데 걸린 시간이 대부분 1분 안쪽이었습니다. 원본 확인은 비싸다는 감각이 제 안에 있었는데, 그 감각이 이 다섯 자리에서는 전부 틀렸습니다. 비쌌던 것은 확인이 아니라 확인하지 않고 세운 계획 쪽이었습니다.

결론을 적기 직전에 보는 것

이 다섯 개를 겪고 나서 결론 문장을 쓰기 직전에 훑는 항목을 다섯 줄로 정리해 뒀습니다. 새로운 원칙이라기보다 그날 틀린 자리를 그대로 옮겨 적은 것에 가깝습니다.

요금·가입 조건을 2차 출처에서 읽었다면, 계획에 넣기 전에 콘솔 화면 한 번을 본다

문서에서 제약 문장을 만났다면, 우회로를 설계하기 전에 그 제약을 한 번 친다

상태 코드나 응답 존재로 판단했다면, 없는 값을 일부러 넣어 같은 답이 오는지 본다

되돌리기 번거로운 행위가 실패한 것처럼 보이면, 재시도 전에 서로 다른 창구 두세 곳에서 결과를 조회한다

비밀값을 가리는 장치를 믿기 전에, 이번 형식의 값 하나를 실제로 통과시켜 기록을 열어 본다

다만 이 방식이 어디서나 성립하지는 않습니다. 원본을 칠 수 없는 대상이 있습니다. 계약 조건, 아직 안 나온 기능, 남의 계정 안쪽이 그렇습니다. 이 글은 콘솔과 API 가 열려 있는 대상에 대한 이야기입니다.

1분이라는 비용도 조건부입니다. 여기서도 업로드 경로를 확인하려면 카드 등록을 먼저 통과해야 했습니다. 확인 자체가 되돌리기 번거로운 행위를 요구하면 그건 1분이 아닙니다. 그럴 때는 순서를 바꾸거나, 확인 비용과 틀렸을 때의 비용을 나란히 놓고 고릅니다.

추정으로 원인을 말하고 나서 실제로 재 봤더니 결론이 뒤집힌 기록도 같은 축에 있습니다. 거기서는 병목이라고 지목한 부분이 병목이 아니었습니다.

확인했다고 믿은 절차가 사실은 아무것도 확인하지 않았던 경우도 정리해 뒀습니다. 이번 글의 200 이야기와 같은 구조입니다.

마무리

모델 하나를 재 보러 가는 길에서 다섯 번 걸렸고, 걸린 자리는 전부 읽은 것과 쳐 본 것이 갈린 자리였습니다. 다섯 번 다 읽은 쪽이 그럴듯했고, 다섯 번 다 쳐 본 쪽이 맞았습니다.

틀린 답은 맞는 답과 겉모습이 똑같습니다. 그래서 어느 쪽이 틀렸는지는 읽어서는 안 갈리고, 결론을 적기 직전에 한 번 만져 봐야 갈립니다. 그 한 번이 대부분 1분입니다.