LLM 도구 페이로드 컨텍스트 트림 (작은 context 모델)

도구 결과는 정상인데 chat SSE가 BadRequestError: input N > model context M(예: 18k > 16k)로 끊기고 sql 이벤트가 없다. 원인 후보를 서빙 --context-length 올리기와 도구 응답 슬림화로 분리한다.

제품 쪽 트림 (우선)

대상전형 조치
describe/search 스키마relation join/targetColumns 등 LLM에 불필요한 그래프 fluff 제거
valueDomainmembers≤N, synonyms≤K 상한
search k / preview rowsk≤3, preview≤8 등 하드캡
도구 호출 폭주FS/편집 도구 제외·recursion 상한 — Agent-SSE-Failfast-and-Tool-Flood-Guard.md

함수명은 제품별(slim_describe_for_llm 등)이나 요지는 “도구 JSON을 모델 context 예산 안으로”.

search vs describe 역할 분리 (필수)

FS 도구를 제외해도 search가 describe급 요약(valueDomain members·expression·relation fluff)을 실으면 candidate 1건만으로 16K를 넘긴다.

도구페이로드 요지
searchcandidate-compact: columns≤~20, relations≤~8; valueDomain/expression/그래프 fluff 드롭
describe열거·도메인·표현식은 여기서만(기존 trim 상한 유지)

스모크: short Q에서 flood=no + SSE sql|error+done. 서빙 context만 올리는 것은 2차 — SGLang-gemma4-llm-serving-cluster-ops.md.

운영 쪽 대안

서빙 엔진(SGLang 등) --context-length를 여유(예: ≥~20k)로 올린다. 트림 후에도 부족할 때만. 클러스터 SGLang 메모는 SGLang-gemma4-llm-serving-cluster-ops.md.

진단 체크

  1. MCP Host/인증이 200·401로 정상인가? (403 Host는 별축 — MCP-Host-Allowlist-DNS-Rebinding.md)
  2. SSE에 tool 호출은 있으나 LLM BadRequest인가?
  3. 트림 배포 후 동일 스모크에서 overflow가 사라졌는가? (그다음 hang/no-sql은 fail-fast 축)

온디맨드 describe (슬림 1차 + Enum 후속)

대용량 describe_table(Enum/valueDomain 포함)이 고정 max_model_len(예: 40960)을 넘기면 BadRequest → SQL 미방출로 이어진다. 서빙 context 재튜닝이 1차 목표가 아닐 때 제품 쪽 패턴:

단계도구/필드요지
1차describe_table컬럼명·타입·hasValueDomain만. 컬럼>N이면 columnNames(+columnsWithValueDomain)
온디맨드get_column_values / describe_columnsEnum members·소수 컬럼 상세만
예산DESCRIBE_JSON_CHARS_MAX · SEARCH_JSON_CHARS_MAX · MULTI_TURN_TOOL_CHARS_MAX단발뿐 아니라 멀티턴 누적 envelope도 캡

MCP 표면은 얇게 유지하고(예: search/describe/execute), 온디맨드는 backend analyst tool로 흡수해도 된다. 채점 축은 Spider2-Quality-Gate-nl2sql.md.

멀티턴 누적 함정

라운드마다 describe 12k를 허용하면 3~4턴에 context를 다시 넘긴다. 스모크에서 overflow가 사라졌다가 재발하면 단발 캡이 아니라 envelope 합을 의심한다.

input+max_tokens 합산 overflow

서빙이 input + max_tokens > context를 BadRequest로 거절하면, 도구 트림만으로는 부족하다.

축전형 조치
completion 예산DEFAULT_MAX_TOKENS 하향(예: 2048→1024)
도구 단발 캡describe≤4k / search≤700 / ondemand≤900; multi-turn envelope≤9k
describe_columnsrequest 컬럼 수 상한(예: ≤3)
execute previewrows≤3
하드 게이트orchestrator+analyst에 ContextEditingMiddleware/ClearToolUsesEdit(예: trigger 32k tokens, keep last 1 tool result) — pre-model로 오래된 ToolMessage body 제거

스모크: overflow=0 후에도 empty-SQL이면 Agent-SSE-Failfast-and-Tool-Flood-Guard.md stash/task 축을 본다.

🔗 관련 문서