Mistral Responses API: Large 4 설정과 OpenAI에서 이전하기

Mistral Responses API에서 mistral-large-4를 사용하고 요청마다 대화 기록을 input에 보냅니다. 서버 상태에 의존하는 대화 연결 매개변수를 제거하고, store를 끈 상태로 모델이 지원하는 추론 강도를 선택합니다. 2026-11-01 기준 Mistral의 Responses API는 공개 프리뷰로 제공됩니다.

Mistral Large 4에 첫 요청 보내기

첫 요청은 현재 Mistral Python SDK와 Mistral API 키로 보냅니다. 먼저 문서에 나온 방식으로 호출한 뒤 기존 Responses 클라이언트를 수정합니다.

Python 3.10 이상이 필요합니다. Studio → API keys에서 키를 만든 뒤 Bash에서 다음 명령을 실행합니다. read가 입력을 기다리면 키를 붙여 넣고 Enter를 누릅니다. 입력한 문자는 화면에 표시되지 않습니다.

python3 -m pip install -U mistralai
read -rs MISTRAL_API_KEY && export MISTRAL_API_KEY

아래 코드를 mistral_responses.py로 저장합니다. 보조 함수는 이후 예제에서도 같은 지침과 공통 요청 설정을 사용하도록 구성합니다.

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
MODEL = "mistral-large-4"
INSTRUCTIONS = "Answer concisely."

def create_response(history, **options):
    result = client.responses.create(
        model=MODEL,
        input=history,
        instructions=INSTRUCTIONS,
        reasoning={"effort": "high"},
        max_output_tokens=4096,
        additional_properties={
            "store": False,
            "background": False,
            "truncation": "disabled",
        },
        **options,
    )
    if result.status != "completed":
        raise RuntimeError(
            f"{result.status}: {result.error or result.incomplete_details}"
        )
    return result

def answer_text(result):
    return "".join(
        part.text
        for item in result.output if item.type == "message"
        for part in item.content if part.type == "output_text"
    )

history = [{"role": "user", "content": "Explain a stateless API in one sentence."}]
response = create_response(history)
print(response.status)
print(answer_text(response))

같은 Bash 세션에서 파일을 실행합니다.

python3 mistral_responses.py

이 예제에서는 completed 다음에 비어 있지 않은 설명이 출력되면 성공한 것으로 확인합니다. 답변 문구는 달라질 수 있습니다. output에는 추론과 함수 호출도 들어갈 수 있으므로 답변 텍스트만 골라 출력합니다.

HTTP 엔드포인트는 https://api.mistral.ai/v1/responses입니다. 직접 보내는 HTTP 요청에는 Authorization: Bearer $MISTRAL_API_KEY 헤더를 사용합니다. 클라이언트가 /responses를 붙이는 방식이라면 기본 URL을 https://api.mistral.ai/v1로 설정합니다.

이후 Python 예제는 이 파일의 변수와 보조 함수를 재사용합니다. 필요한 예제를 파일 끝에 추가합니다. 파일을 다시 실행하면 포함된 모든 생성 요청이 다시 실행됩니다.

OpenAI Responses에서 바꿔야 할 매개변수

기존 OpenAI Responses 요청을 재사용하기 전에 HTTP 요청의 JSON 필드를 아래 조건에 맞춥니다. Mistral의 Responses API 참조 문서는 2026-11-01 기준 허용되는 값을 다음과 같이 정의합니다.

Responses 요청 매개변수	Mistral 요구 사항	이전할 때 할 일
`previous_response_id`	생략하거나 `null`을 보냅니다.	이전 응답의 출력 항목을 `input`에 다시 보냅니다.
`conversation`	생략하거나 `null`을 보냅니다.	애플리케이션에서 대화 기록을 관리합니다.
`store`	생략하거나 `false` 또는 `null`을 보냅니다.	`true`를 제거하고 저장된 응답에 의존하지 않습니다.
`background`	반드시 `false`여야 하며 기본값도 `false`입니다.	백그라운드 실행과 해당 작업의 상태를 조회하는 코드를 제거합니다.
`truncation`	반드시 `"disabled"`여야 하며 기본값도 같습니다.	요청 전에 컨텍스트 크기를 관리합니다.
`prompt`	생략하거나 `null`을 보냅니다.	프롬프트 내용을 `input`과 `instructions`에 넣습니다.
`moderation`	생략하거나 `null`을 보냅니다.	이 호환성 필드에 설정된 값을 제거합니다.
`top_logprobs`	생략하거나 `0` 또는 `null`을 보냅니다.	양수 값을 제거합니다.
`max_tool_calls`	허용되지만 현재는 무시됩니다.	실행 횟수 제한은 애플리케이션에서 적용합니다.
`reasoning.effort`	선택한 모델이 지원하는 값이어야 합니다.	아래 모델별 설정값을 사용합니다.
`tools`	클라이언트에서 실행하는 함수이며 네임스페이스로 묶을 수 있습니다.	제공업체가 실행하는 도구에 대한 의존성을 수정합니다.
`max_output_tokens`	추론 토큰과 답변 텍스트의 토큰을 함께 포함합니다.	두 부분에 필요한 출력 토큰을 확보합니다.

Python SDK의 키워드 인수가 모든 HTTP 필드와 일대일로 대응하지는 않습니다. 현재 Responses 구현은 store, background, truncation을 additional_properties로 받습니다. 첫 번째 예제도 이 방식을 사용합니다.

이 차이는 제공업체별 설정에 반영합니다. 엔드포인트만 바꿔서는 모든 도구, 대화 연결 방식, 스트리밍 처리 코드의 호환성을 확인할 수 없습니다. Messages, Chat Completions, Responses 호환성 안내는 함수 호출의 전체 왕복 과정을 확인해야 하는 이유를 설명합니다.

사용 가능한 모델과 기능

이 예제에서는 mistral-large-4를 사용하고, 모델을 바꿀 때 지원 기능을 다시 확인합니다. Mistral의 출시 발표는 Large 4를 포함해 Mistral이 호스팅하는 모든 채팅 모델을 지원한다고 설명합니다.

지원 기능 목록에는 텍스트 입출력, 구조화된 출력, 스트리밍, 함수 호출, 모델별 추론 기능이 포함됩니다. 이미지 입력에는 이미지 이해 기능이 있는 모델이 필요하며 이미지 URL이나 base64 데이터 URL을 사용할 수 있습니다. 파일은 HTTPS URL, base64 데이터 URL, 업로드한 파일 ID로 전달할 수 있으며 지원 여부는 모델에 따라 달라집니다.

구조화된 출력은 text.format으로 JSON 모드 또는 JSON Schema를 설정합니다. 함수 도구는 애플리케이션에서 실행합니다. 공개된 구현은 클라이언트 실행 함수만 지원하므로 제공업체가 실행하는 web_search를 변경 없이 요청에 넣지 않습니다.

추론 강도는 Responses의 중첩 필드 reasoning.effort로 설정합니다. 아래 값은 2026-11-01에 확인한 Mistral의 추론 가이드를 따릅니다.

모델	지원하는 추론 강도	선택 기준
`mistral-large-4` / `mistral-large-4-0`	`low`, `medium`, `high`	예제는 `high`로 시작합니다. 지연 시간이나 토큰 사용량이 중요하면 낮은 설정과 비교합니다.
`mistral-small-2603`	`none`, `high`	추론 모드가 필요하면 `high`를 사용합니다.
`mistral-medium-3-5`	`none`, `high`	기존 연동에서 참고합니다. 사용 중단 예정(deprecated)으로 분류된 모델입니다.

Large 4는 none, minimal, xhigh, max를 허용하지 않습니다. 초기 Large 4 프리뷰 예제를 복사했다면 none을 low로 바꿉니다. SDK의 공통 열거형에 값이 있다는 이유만으로 모든 모델이 그 값을 지원한다고 판단하지 않습니다.

Large 4 모델 카드에도 공개 프리뷰 상태가 표시되어 있습니다. Medium 3.5 카드는 2026-10-31을 deprecated 상태로 전환된 날짜로 명시합니다. 신규 연동에는 Large 4를 권장합니다.

여러 차례 대화를 이어 가고 함수 결과 반환하기

추론과 함수 호출을 포함해 전체 항목 기록을 보존합니다. 화면에 보여 주는 답변 텍스트만으로는 완전한 대화 기록을 구성할 수 없습니다.

대화 이어 가기

이전 output의 모든 항목을 추가한 다음 사용자의 새 메시지를 추가합니다. 첫 번째 예제 뒤에 다음 코드를 붙입니다.

history.extend(response.output)
history.append({"role": "user", "content": "What must the client send next time?"})
response = create_response(history)
print(answer_text(response))
history.extend(response.output)

두 번째 요청에는 첫 사용자 메시지, 첫 응답 전체, 후속 질문이 들어갑니다. 보조 함수는 instructions도 다시 보냅니다.

이것이 문서에서 안내하는 previous_response_id의 대체 방식입니다. 응답 ID만 보관해서는 이 무상태 엔드포인트에 대화 기록을 전달할 수 없습니다. 출력한 답변만 저장하면 함께 반환된 다른 항목이 빠집니다.

함수 결과 반환하기

함수를 로컬에서 실행한 뒤 해당 호출과 같은 call_id를 사용해 결과를 반환합니다. Mistral의 함수 호출 예제는 type, name, description, parameters를 하나의 도구 객체에 배치합니다. 다음 코드는 같은 구조를 사용해 로컬에서 덧셈을 수행하며 별도의 대화 기록을 사용합니다.

import json

TOOLS = [{
    "type": "function",
    "name": "add",
    "description": "Add two integers.",
    "parameters": {
        "type": "object",
        "properties": {
            "a": {"type": "integer"},
            "b": {"type": "integer"},
        },
        "required": ["a", "b"],
        "additionalProperties": False,
    },
}]
tool_history = [{"role": "user", "content": "Use add to calculate 19 + 23."}]
response = create_response(
    tool_history,
    tools=TOOLS,
    tool_choice={"type": "function", "name": "add"},
    parallel_tool_calls=False,
)
tool_history.extend(response.output)

calls = [item for item in response.output if item.type == "function_call"]
if len(calls) != 1 or calls[0].name != "add":
    raise RuntimeError("Expected exactly one add call.")

call = calls[0]
args = json.loads(call.arguments)
if (
    not isinstance(args, dict)
    or set(args) != {"a", "b"}
    or any(type(args[name]) is not int for name in ("a", "b"))
):
    raise ValueError("Expected two integer arguments.")

result = args["a"] + args["b"]
print("Local result:", result)
tool_history.append({
    "type": "function_call_output",
    "call_id": call.call_id,
    "output": json.dumps({"result": result}),
})
response = create_response(
    tool_history,
    tools=TOOLS,
    tool_choice="none",
    parallel_tool_calls=False,
)
print(answer_text(response))
tool_history.extend(response.output)

Local result: 42가 출력되고, 이어지는 답변이 그 결과를 사용하는지 확인합니다. 모델이 사용하는 답변 문구는 달라질 수 있습니다.

첫 요청은 add 호출을 강제합니다. 두 번째 요청은 API 참조 문서에 따라 "none"으로 추가 호출을 막습니다. 따라서 예제는 두 번의 생성 요청과 한 번의 로컬 실행으로 제한됩니다.

단계 수가 정해져 있지 않은 에이전트 루프에서는 반복 횟수와 실행 횟수의 상한을 직접 적용합니다. max_tool_calls는 현재 무시되므로 이 필드로 실행 횟수를 제한할 수 없습니다.

함수 결과를 추가하기 전에 반환된 출력 전체를 기록에 보존합니다. 결과는 출력 항목의 id가 아닌 call_id로 연결합니다. 여러 함수 호출을 허용한다면 각 호출을 검증하고 모든 결과를 반환한 뒤 다음 응답을 요청합니다.

기록이 늘어나기 전에 입력 토큰 계산하기

다음 요청 전체를 대상으로 기록, 지침, 도구 정의까지 포함해 토큰을 계산합니다. 최신 사용자 메시지만 계산하면 애플리케이션이 다시 보낼 내용을 빠뜨리게 됩니다.

함수 예제 뒤에 다음 코드를 추가합니다.

next_input = tool_history + [
    {"role": "user", "content": "Explain that calculation in one sentence."}
]
count = client.responses.count_input_tokens(
    model=MODEL,
    input=next_input,
    instructions=INSTRUCTIONS,
    tools=TOOLS,
    reasoning={"effort": "high"},
    parallel_tool_calls=False,
    tool_choice="auto",
)
print(count.input_tokens)

이 코드는 POST /v1/responses/input_tokens를 호출하고 input_tokens를 출력합니다. 답변을 생성하지 않고 입력만 계산합니다. 이후 답변을 생성할 때도 같은 모델, 입력, 지침, 도구를 사용합니다.

계산한 토큰 수를 선택한 모델의 컨텍스트 창과 비교하고 출력에 필요한 공간을 남깁니다. truncation은 "disabled"여야 하므로 기록을 언제 줄일지는 애플리케이션에서 결정합니다.

기록을 관리할 때는 함수 호출과 해당 결과를 함께 유지합니다. 도구 호출과 결과가 오가는 도중의 항목을 임의로 삭제하지 않습니다.

토큰 수만으로는 비용을 추정할 수 없습니다. 대화가 반복될 때의 비용과 캐시 영향을 계산하려면 Mistral의 현재 API 요금을 확인합니다.

이전 과정에서 발생하는 문제 진단하기

요청 설정을 먼저 확인한 다음 상태와 출력 항목을 살펴봅니다. 발생한 증상에 맞는 항목을 확인합니다.

SDK가 요청 전송 전에 키워드 인수를 거부합니다. 설치된 SDK와 메서드의 인수 정의를 확인합니다. 여기서 사용하는 SDK에서는 store, background, truncation을 additional_properties 안에 넣습니다.
API가 요청을 거부합니다. 첫 번째 텍스트 예제로 요청을 단순화합니다. 모델 ID, 지원하는 추론 강도, 호환성 표를 확인합니다. 해당 요청이 성공하면 선택 필드를 하나씩 다시 추가합니다.
모델이 이전 맥락을 잃습니다. 다음 요청의 input 배열을 확인합니다. 응답 ID만 넣지 않고 이전 메시지와 출력 항목 전체를 포함해야 합니다.
응답에 답변 텍스트가 없습니다. status, error, incomplete_details를 확인합니다. 실행을 기다리는 함수 호출이 있는지도 살펴봅니다. 출력 토큰 예산을 소진했다면 예산을 늘리거나 모델이 지원하는 범위에서 추론 강도를 낮춥니다.
요청이 잘못된 경로로 전송됩니다. 최종 URL을 https://api.mistral.ai/v1/responses와 비교합니다. 기본 URL과 엔드포인트 오류 해결 안내는 경로를 구성할 때 자주 발생하는 실수를 설명합니다.

스트리밍에서는 stream=True를 설정하고 Responses 이벤트를 처리합니다. 공식 Python 스트리밍 예제는 각 이벤트를 frame.data로 읽습니다. 텍스트는 response.output_text.delta로 전달되고, 완료 시에는 response.completed가 전달됩니다.

response.failed, response.incomplete, error 이벤트도 처리합니다. 텍스트 일부를 받았다는 사실만으로 성공적인 완료를 확인할 수는 없습니다. 백그라운드 생성이 비활성화되어 있으므로 이 설정에는 상태를 반복 조회하는 폴링 코드가 필요하지 않습니다.

Responses, Chat Completions, Conversations 선택하기

항목 기반 형식이 애플리케이션에 맞고 대화 기록과 함수 실행을 직접 관리하려면 Responses를 선택합니다.

애플리케이션에 필요한 것	먼저 검토할 API	이유
Responses 입출력 항목과 Responses 스트리밍 이벤트	Responses API	해당 형식을 유지하면서 애플리케이션이 상태와 함수를 관리합니다.
메시지 기반의 기존 연동 유지	Chat Completions	메시지 중심의 요청 및 응답 처리 코드를 유지할 수 있습니다.
저장된 대화 이어 가기 또는 Mistral이 실행하는 도구	Conversations API	대화 ID와 서버 실행 도구를 위한 별도 인터페이스를 제공합니다.

Mistral의 Chat Completions 가이드는 메시지 기반 형식을 설명합니다. Conversations 참조 문서는 conversation_id로 대화를 이어 가는 방법을 안내합니다.

Mistral이 실행하는 검색은 Conversations와 Agents에 web_search와 web_search_premium으로 문서화되어 있습니다. 이 기능은 Responses에서 클라이언트가 실행하는 함수 도구와 별개입니다.

현재 애플리케이션이 저장된 대화의 연결이나 서버 실행 도구에 의존한다면 요청 본문을 이전하기 전에 Conversations를 검토합니다. 애플리케이션이 이미 기록과 함수 실행을 관리한다면 텍스트 요청, 후속 대화, 함수 호출의 전체 왕복 과정을 확인합니다. 그다음 전체 에이전트를 연결합니다.