후보 페이지 출력 11: 먼저 필요한 만큼만 읽기

English · 측정 결과

riido-hints --limit 20은 후보를 20개씩 출력한다. 나머지를 버리지 않고 page.next_cursor로 이어서 받을 수 있다. 기존 기본값은 전체 출력이며, 순위 계산·모델·보조 검색 정책은 바꾸지 않는다.

사용

원본 예제의 JSON 요청을 catalog.json에 저장한 뒤 실행한다. 모델 없이도 사용할 수 있다.

go run ./cmd/riido-hints --identifier-hints --limit 2 < catalog.json > page-1.json

page-1.json의 page.next_cursor 값을 복사해서 같은 입력·옵션으로 다음 페이지를 요청한다.

go run ./cmd/riido-hints --identifier-hints --limit 2 \
  --cursor 'NEXT_CURSOR_FROM_PAGE_1' < catalog.json

next_cursor가 없으면 끝이다. inspection_rank는 페이지 안 순서가 아니라 전체 결과의 순위다. page에는 전체 후보 수, 시작 위치, 반환 개수, 일관성 확인용 해시가 있다. 페이지 크기는 1~4,096개이며 다음 요청에서 바꿀 수 있다. --limit 0 또는 옵션 생략은 기존 전체 출력이고 cursor와 함께 사용할 수 없다.

질문, snapshot, 문서 ID·내용·순서, 외부 힌트, 모델 해시나 검색 옵션이 달라지면 이전 cursor를 거부한다. 같은 요청에서도 계산된 전체 순위·점수가 달라지면 거부한다. 따라서 페이지 중간에 자료나 정책을 바꾸고 조용히 이어 붙이지 않는다. 잘못된 cursor에 대해서는 부분 결과를 출력하지 않는다.

cursor는 인증 토큰이 아니다. 위치와 요청/결과 해시를 담는 일관성 표식이며, 서명하거나 서버에서 보관하지 않는다. 호출자가 계속 같은 접근 가능한 카탈로그를 전달해야 한다. 이 기능이 접근 권한을 부여하거나 저장소를 대신 읽어주지는 않는다. 서버 캐시도 없으므로 매 페이지에서 색인과 검색을 다시 계산한다.

실제 CLI 측정

앞선 10의 감사한 3,009개 함수 카탈로그와 첫 해시 순서 질문 하나를 사용했다. 이는 페이지 전송 검증이며 새로운 2,948개 질문 성능 시험이 아니다.

출력	바이트
기존 전체 응답	486,628
첫 20개 페이지	3,878
151페이지를 전부 읽은 합계	558,544

첫 출력은 99.20% 감소했다. 반면 모든 페이지를 읽으면 메타데이터 때문에 전체 출력보다 약 14.8% 커졌다. 151번의 별도 프로세스 호출·입력 재전송·재검색은 약 20.60초였다. 이 수치는 첫 페이지 지연이나 서버 처리량이 아니다. 필요한 후보를 찾고 일찍 멈출 때 출력량 이점이 생긴다. 실제 LLM 토큰·요금·작업 성공률 절감은 측정하지 않았다.

모든 페이지를 결합한 후보 ID·전역 순위·점수가 기존 전체 결과와 정확히 같았다. 페이지 옵션을 끈 응답도 변경 전과 바이트 단위로 같았다. 원시 요청에는 공개 코드가 들어 있으므로 Git에 올리지 않고 로컬에서만 측정했다.

검증과 다음 작업

회귀 시험은 전체 순서 복원, 페이지 크기 변경, 검색 정책별 결과, snapshot/질문/문서 변경 거부, 잘못된 위치·형식·추가 필드 거부를 다룬다. 기존 보조 검색·모델·입력 한도 시험도 유지한다.

go test -race ./cmd/riido-hints

실제 에이전트가 몇 페이지에서 정답을 검증하고 멈추는지, 재검색 비용이 얼마나 드는지 다음 작업 흐름에서 측정해야 한다. 페이지 출력을 모든 검색의 속도 개선으로 간주하지 않는다. 학습 모델도 후보 순위뿐 아니라 페이지 수·추가 검색 비용을 고려한 기준선과 비교해야 한다.