Anthropic Messages API¶

mlxcel은 mlxcel serve와 mlxcel-server 양쪽에서 Anthropic 호환 Messages API를 제공합니다. SDK의 base URL을 mlxcel 서버로 지정하면 공식 Anthropic SDK의 client.messages.create(...) 호출을 사용할 수 있습니다.

엔드포인트¶

메서드	경로	설명
`POST`	`/v1/messages`	메시지 생성(동기 또는 SSE).
`POST`	`/v1/messages/count_tokens`	요청이 소비할 프롬프트 토큰 수 계산.

/v1이 없는 별칭(/messages, /messages/count_tokens)도 함께 마운트됩니다.

빠른 예시¶

from anthropic import Anthropic

client = Anthropic(base_url="http://127.0.0.1:8080", api_key="sk-no-auth")
msg = client.messages.create(
    model="Qwen3.5-0.8B-4bit",
    max_tokens=64,
    system="Be terse.",
    messages=[{"role": "user", "content": "Reply with: hello"}],
)
print(msg.content[0].text)

curl http://127.0.0.1:8080/v1/messages \
  -H 'content-type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  -d '{"model":"Qwen3.5-0.8B-4bit","max_tokens":64,"messages":[{"role":"user","content":"Reply with: hello"}]}'

지원 요청 표면¶

필드	지원 범위
`model`	요청 스키마에서 필수이지만 로드된 모델과 대조하지 않으며, 응답에는 서비스 중인 모델 id가 담깁니다.
`system`	문자열 또는 text 블록 배열. user/assistant 턴 앞에 렌더링됩니다.
`messages`	`user` 및 `assistant` 턴. content는 문자열 또는 block 배열일 수 있습니다. 배열 안의 `system` 턴도 받아서 인접한 user 턴에 합칩니다.
`max_tokens`	최대 생성 토큰 수. 생략하면 서버 기본값을 사용합니다.
`stop_sequences`	생성 중단 후 `stop_reason: "stop_sequence"`로 보고합니다.
`stream`	Anthropic SSE 이벤트를 방출합니다.
`temperature`, `top_p`, `top_k`	mlxcel sampling 설정으로 매핑됩니다.
`tools` / `tool_choice`	클라이언트 정의 function 도구를 내부 OpenAI-style tool schema로 변환합니다.
`thinking`	응답에 `thinking` 블록을 포함합니다. `budget_tokens`는 공용 reasoning 예산 처리로 전달됩니다.

metadata, container, service_tier 같은 알 수 없는 최상위 필드는 SDK 호환성을 위해 수락하고 무시합니다.

콘텐츠 블록¶

메시지 content는 text, image, tool call, tool result를 섞을 수 있습니다.

[
  {"type": "text", "text": "What is in this image?"},
  {"type": "image", "source": {"type": "url", "url": "https://example.com/x.png"}},
  {"type": "tool_result", "tool_use_id": "toolu_1", "content": "sunny"}
]

user 턴의 image 블록은 multimodal media 파이프라인으로 전달됩니다. tool_result 블록도 이미지를 포함할 수 있으므로, 비전 모델이 다음 턴에서 도구가 생성한 이미지를 소비할 수 있습니다. input_schema가 없는 Anthropic server tool(예: hosted web_search, code_execution)은 수락되지만 mlxcel이 hosted 도구를 실행하지 않기 때문에 prompt 렌더링 전 제거됩니다.

응답과 스트리밍¶

비스트리밍 응답은 필요에 따라 text, thinking, tool_use 블록을 담은 순서 있는 content 배열과 stop_reason, usage를 포함합니다. extended thinking을 켠 경우, 생성 프롬프트가 이미 추론 블록을 연 상태로 끝나는 템플릿(<think>\n으로 끝남)은 첫 토큰부터 그 추론을 thinking 블록으로 반환합니다.

프롬프트 캐시가 켜져 있고 extended thinking을 켰다면 서버는 일반 응답마다 반환한 thinking 블록을 기억합니다. 이후 요청이 그 assistant 턴을 해당 블록 없이 다시 보내면 추론을 다시 넣어 주므로, 턴이 생성 당시와 같은 형태로 렌더링되고 프롬프트 캐시도 계속 일치합니다.

스트리밍은 Anthropic 이벤트 순서(message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop)를 따릅니다. 도구 호출은 tool_use content block으로 스트리밍됩니다.

토큰 카운트¶

POST /v1/messages/count_tokens는 요청을 채팅 템플릿으로 렌더링하고 생성 없이 {"input_tokens": N}을 반환합니다.

서버가 생성을 할 수 없을 때(임베딩 전용 또는 리랭킹 전용 모드, 채팅 모델 미로드) 두 라우트 모두 Anthropic 오류 형식으로 501 Not Implemented를 반환합니다.