콘텐츠로 이동

클라이언트 연동

개요

이 페이지는 배포한 서빙 스택에 클라이언트와 코딩 에이전트를 연동하는 방법을 설명합니다. MiniMax-M2.7은 일반적인 OpenAI 호환 모델과 도구 호출 및 reasoning 출력 처리 방식이 다르므로 이 차이를 중심으로 다룹니다.

엔드포인트

항목 값
게이트웨이 포트 80
Base URL http://<gateway>:80/v1
모델 목록 GET /v1/models
채팅 POST /v1/chat/completions
인증 없음(--api-key 미사용)

인증은 서빙 스택의 범위에 포함되지 않습니다

서빙 스택은 인증을 수행하지 않습니다. 외부에 공개할 때는 인그레스 계층에서 인증과 권한 부여를 처리해야 합니다. 이 요건을 충족하지 않고 클러스터 외부에 공개하면 누구나 모델을 호출할 수 있습니다.

GET /v1/models로 모델 ID를 확인합니다. 다음 예제의 <model-id>에는 이 값을 사용합니다.

컨텍스트 한도

항목 값
--max-model-len 204,800
라우터의 prefix 매칭 한도 204,800

입력과 출력의 합이 204,800을 초과하면 요청이 거부됩니다. 클라이언트는 이 한도를 넘지 않도록 대화를 잘라내거나 요약해야 합니다.

라우터의 prefix 매칭 한도는 --max-model-len과 같습니다. 따라서 prefix 캐시를 고려한 라우팅은 전체 컨텍스트를 대상으로 캐시 hit을 예측할 수 있습니다. 기본값인 autoTune이 활성화된 상태에서 라우터는 프롬프트를 --block-size 단위(4,096 토큰)로 해시합니다. 따라서 한 블록보다 짧은 prefix와 프롬프트 끝의 불완전한 블록은 추적하지 않습니다(서빙 설정 › 512 토큰의 prefix 재사용 단위 참고).

파라미터 값
temperature 1.0
top_p 0.95
top_k 40

모델 제공자가 권장하는 값이며 이 모델은 이 값으로 평가했습니다. 값을 변경하면 정확도를 다시 측정하세요.

도구 호출

MiniMax-M2.7은 OpenAI JSON 대신 XML 형식으로 도구 호출을 생성합니다.

<minimax:tool_call>
  <invoke name="tool_name">
    <parameter name="arg">value</parameter>
  </invoke>
</minimax:tool_call>

MiniMax-M2.7이 생성한 XML 형식의 도구 호출은 서버의 minimax_m2 파서가 OpenAI 호환 tool_calls 필드로 변환합니다. 따라서 클라이언트는 표준 형식으로 응답을 받으며 XML을 직접 파싱할 필요가 없습니다.

코딩 에이전트 연동

mini-swe-agent

Validated입니다. 배지의 의미는 레퍼런스 디자인 › 상태 배지를 참고하세요. Target Configuration 검증의 에이전트 워크로드에서 사용한 에이전트입니다. RBLN NPU에서 MiniMax-M2.7 서빙에서처럼 LiteLLM을 통해 연결합니다. 연결 대상은 vllm serve가 제공하는 OpenAI 호환 엔드포인트입니다.

1
2
export OPENAI_API_BASE=http://<gateway>:80/v1
mini-swe-agent --model openai/<model-id>

서버가 인증을 요구하지 않으므로 OPENAI_API_KEY에 임의의 값을 넣어도 동작합니다. 인그레스에서 인증을 적용했다면 해당 인증 값을 설정해야 합니다.

다른 에이전트

에이전트 상태
OpenCode Unverified. 앞의 Base URL로 OpenAI 호환 프로바이더를 설정하세요. 포함된 예제는 없습니다.
기타 OpenAI 호환 클라이언트 Base URL만 변경하면 연결할 수 있습니다. reasoning 필드 처리는 연동 확인 순서의 3단계와 5단계를 따릅니다.

연동 확인 순서

  1. GET /v1/models로 모델 ID를 확인합니다.
  2. 짧은 프롬프트로 비스트리밍 요청을 보내 content가 반환되는지 확인합니다. reasoning이 끝날 수 있도록 max_tokens를 충분히 크게 설정합니다. 모델은 reasoning을 먼저 생성하며 reasoning이 끝나기 전에 응답이 잘리면 content가 반환되지 않습니다.
  3. 같은 요청의 응답에서 reasoning이 별도 필드로 반환되는지 확인합니다. 응답에는 reasoning_content 필드가 없으므로 이 필드만 읽는 클라이언트는 reasoning을 받지 못합니다. reasoning이 content에 섞여 반환된다면 서버의 --reasoning-parser 설정이 누락된 것입니다.
  4. 도구 정의를 포함한 요청을 보내 tool_calls가 표준 형식으로 반환되는지 확인합니다. 원시 XML이 content에 보이면 --tool-call-parser 또는 --enable-auto-tool-choice가 누락된 것입니다.
  5. 도구 실행 결과를 돌려주는 두 번째 요청에 이전 응답의 reasoning 필드를 포함합니다.

운영 중 확인할 메트릭은 운영을 참고하세요.