다중 턴 대화 가이드

LLM에는 고유한 기억이 없습니다 — 모델은 방금 전에 사용자가 말한 내용을 기억하지 못합니다. “멀티턴 대화”란 사실상 매 요청마다 전체 대화 기록을 전송하는 것을 의미합니다. 이 가이드는 APIYI의 네 가지 호출 형식이 각각 그 기록을 어떻게 유지하는지와 주의해야 할 함정을 설명합니다.

예제는 엔드포인트 https://api.apiyi.com와 귀하의 APIYI 토큰을 사용합니다. 참조되는 모델: gpt-5.4-mini, deepseek-v4-pro, gemini-3.5-flash, claude-sonnet-4-6.

핵심 원칙: 히스토리를 직접 유지

한 문장으로 요약됩니다: 모델은 상태를 가지지 않으며, 여러분(클라이언트)이 히스토리를 유지하고 매 턴마다 그 전체를 다시 전송합니다.

Turn 1: send [user Q1]                              → get [reply 1]
Turn 2: send [user Q1, reply 1, user Q2]            → get [reply 2]
Turn 3: send [user Q1, reply 1, user Q2, reply 2, user Q3] → get [reply 3]

각 새 턴마다 이전 사용자 메시지와 모델 응답을 히스토리 배열의 끝에 추가한 다음, 전체를 전송합니다. 형식 간의 차이는 히스토리 배열의 이름과 역할 표기 방식뿐입니다.

APIYI에서는 항상 “히스토리를 직접 유지”하는 방식을 사용하십시오. OpenAI Responses의 previous_response_id처럼 서버 측 대화 상태에 의존하지 마십시오. 이는 아래의 OpenAI 네이티브 섹션에서 설명하듯 게이트웨이를 통해서는 정상 동작이 보장되지 않습니다.

OpenAI 호환 모드(모델 전반에서 작동)

가장 범용적인 접근 방식은 엔드포인트 /v1/chat/completions입니다. 기록은 messages 배열에 저장되며, 각 항목에는 role(system / user / assistant)가 포함됩니다. model 문자열을 바꾸면 같은 코드로 다른 모델을 구동할 수 있습니다(gpt, deepseek, claude, gemini…).

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.apiyi.com/v1")

messages = [{"role": "system", "content": "You are a friendly assistant."}]

def chat(user_input, model="gpt-5.4-mini"):
    messages.append({"role": "user", "content": user_input})
    resp = client.chat.completions.create(model=model, messages=messages)
    reply = resp.choices[0].message.content
    messages.append({"role": "assistant", "content": reply})  # append reply to history
    return reply

print(chat("My name is Alice and I'm 28. Please remember."))
print(chat("How old am I? And plus 5?"))   # remembers → 28, 33

import OpenAI from 'openai';

const client = new OpenAI({ apiKey: 'YOUR_API_KEY', baseURL: 'https://api.apiyi.com/v1' });
const messages = [{ role: 'system', content: 'You are a friendly assistant.' }];

async function chat(userInput, model = 'gpt-5.4-mini') {
  messages.push({ role: 'user', content: userInput });
  const resp = await client.chat.completions.create({ model, messages });
  const reply = resp.choices[0].message.content;
  messages.push({ role: 'assistant', content: reply });   // append reply to history
  return reply;
}

console.log(await chat("My name is Alice and I'm 28. Please remember."));
console.log(await chat('How old am I?'));

{/* Turn 2: include both the question and answer from turn 1 */}
curl https://api.apiyi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "My name is Alice and I am 28. Please remember."},
      {"role": "assistant", "content": "Got it: your name is Alice and you are 28."},
      {"role": "user", "content": "How old am I?"}
    ]
  }'

하나의 코드베이스, 여러 모델: model를 deepseek-v4-pro, claude-sonnet-4-6, gemini-3.5-flash 또는 다른 모델로 바꾸기만 하면 멀티턴 로직은 동일하게 유지됩니다. 모델 및 가격 개요를 참조하십시오.

추론 모델의 기록 처리

deepseek-v4-pro 같은 추론 모델은 추가 reasoning_content(사고의 흐름) 필드를 반환합니다.

기록에는 content만 남기고, reasoning_content는 다시 전달하지 마십시오. 생각 과정은 현재 턴의 중간 산출물일 뿐입니다. 이를 다시 전달하면 tokens를 낭비하고 상위 규칙을 위반합니다(DeepSeek의 직접 API는 이에 대해 400을 반환하기도 합니다). 기록에 추가할 때는 content만 취하십시오:

messages.append({"role": "assistant", "content": resp.choices[0].message.content})
# do NOT include resp.choices[0].message.reasoning_content

추론 모델 응답 파싱에 대한 자세한 내용은 추론 모델 출력를 참조하십시오.

OpenAI 네이티브 형식 (Responses API)

엔드포인트 /v1/responses. 멀티턴의 경우, 전체 기록을 input 배열로 전달합니다(각 항목에 role / content 포함) — 호환 모드와 동일한 자체 관리 방식입니다:

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.apiyi.com/v1")

resp = client.responses.create(
    model="gpt-5.4-mini",
    input=[
        {"role": "user", "content": "Remember the codeword: purple elephant."},
        {"role": "assistant", "content": "Got it, the codeword is purple elephant."},
        {"role": "user", "content": "What's the codeword?"},
    ],
)
print(resp.output_text)   # The codeword is: purple elephant.

서버 측 상태에 의존하지 마십시오. 예: previous_response_id / conversation / store. APIYI 게이트웨이를 통해 테스트한 결과, previous_response_id를 전달해도 오류는 발생하지 않지만(200을 반환하지만), 다음 턴에서는 이전 내용을 기억하지 못하며, GET /v1/responses/{id}를 사용할 수 없습니다. 따라서 APIYI에서는 위와 같이 Responses API를 자체 관리 기록(input 배열)과 함께 사용하십시오.

Gemini 네이티브 형식

엔드포인트 /v1beta/models/{model}:generateContent. 기록은 contents 배열에 있습니다. 역할은 user / model입니다(assistant가 아니며), 각 항목의 content는 parts에 들어갑니다.

from google import genai

client = genai.Client(api_key="YOUR_API_KEY",
                      http_options={"base_url": "https://api.apiyi.com"})

contents = [
    {"role": "user", "parts": [{"text": "Remember the codeword: purple elephant."}]},
    {"role": "model", "parts": [{"text": "Got it: purple elephant."}]},
    {"role": "user", "parts": [{"text": "What's the codeword?"}]},
]
resp = client.models.generate_content(model="gemini-3.5-flash", contents=contents)
print(resp.text)   # The codeword is: purple elephant.

더 간단하게는: 공식 google-genai SDK의 client.chats.create(...)가 contents 이력을 대신 유지합니다 — send_message만 호출하면 되며, 수동으로 이어 붙일 필요가 없습니다.

Gemini 3 시리즈 응답은 각 부분에 thoughtSignature를 부착합니다. 일반 텍스트 멀티턴에서는 text만 다시 전달해도 컨텍스트를 유지하기에 충분하며(토큰도 더 적게 듭니다); function calling처럼 엄격한 추론 연속성이 필요한 경우에만 thoughtSignature를 원문 그대로 되돌려 보내야 합니다 — 공식 SDK가 이를 자동으로 처리합니다. Gemini Native Calls 및 함수 호출을 참조하십시오.

Anthropic 네이티브 형식

엔드포인트 /v1/messages. 히스토리는 역할이 user / assistant인 messages 배열에 있습니다. content는 일반 문자열일 수 있습니다. 참고로 max_tokens는 필수입니다.

import requests

def chat(messages):
    r = requests.post(
        "https://api.apiyi.com/v1/messages",
        headers={
            "content-type": "application/json",
            "anthropic-version": "2023-06-01",
            "x-api-key": "YOUR_API_KEY",
        },
        json={"model": "claude-sonnet-4-6", "max_tokens": 200, "messages": messages},
        timeout=60,
    )
    return "".join(b["text"] for b in r.json()["content"] if b["type"] == "text")

messages = [{"role": "user", "content": "Remember the codeword: purple elephant."}]
reply = chat(messages)
messages.append({"role": "assistant", "content": reply})       # append reply
messages.append({"role": "user", "content": "What's the codeword?"})
print(chat(messages))   # The codeword is: purple elephant.

또한 base_url을 https://api.apiyi.com로 지정하면 공식 anthropic SDK를 사용할 수 있습니다. 응답은 content 블록 배열입니다. 파싱 세부 정보는 Claude Streaming & Responses에서 확인할 수 있습니다.

네 가지 형식 비교

항목	OpenAI 호환	OpenAI 네이티브 (Responses)	Gemini 네이티브	Anthropic 네이티브
엔드포인트	`/v1/chat/completions`	`/v1/responses`	`/v1beta/…:generateContent`	`/v1/messages`
히스토리 필드	`messages`	`input`	`contents`	`messages`
역할	system/user/assistant	user/assistant	user/model	user/assistant
콘텐츠 형식	`content` 문자열	`content` 문자열	`parts: [{text}]`	`content` 문자열
히스토리 소유자	사용자	사용자	사용자	사용자
서버 측 상태	없음	⚠️ 사용할 수 없음	없음	없음
모델 간	✅ 전환 `model`	OpenAI 전용	Gemini 전용	Claude 전용

선택 기준: 여러 벤더에 걸쳐 하나의 코드베이스를 원하면 → OpenAI 호환 모드를 선호하십시오. 벤더의 네이티브 전용 기능(Gemini thought signatures / 코드 실행, Claude thinking 블록 및 캐싱, OpenAI 내장 tools)이 필요하면 → 해당 네이티브 형식을 사용하십시오.

자주 묻는 질문

대화가 길어질수록 비용이 더 많이 들까요?

그렇습니다. 매 턴마다 전체 이력을 다시 전송하므로 input tokens는 턴 수에 따라 늘어나며 그에 따라 비용도 증가합니다. 비용을 줄이는 핵심 방법은 컨텍스트 캐싱입니다. 동일한 이력 접두사는 자동으로 캐시 요율을 적용받아(정가보다 훨씬 낮음) 처리됩니다. OpenAI 캐싱, Claude 캐싱, Gemini 캐싱을 참고하십시오.

몇 턴까지 유지해야 합니까? 컨텍스트 윈도우를 초과하면 어떻게 됩니까?

정해진 규칙은 없지만, 이력이 길수록 비용이 더 많이 들고 모델의 컨텍스트 윈도우를 초과할 수 있습니다. 일반적인 전략은 다음과 같습니다. (1) 슬라이딩 윈도우 — 최근 N턴만 유지합니다. (2) 요약 압축 — 이전 턴을 시스템 prompt의 한 단락으로 압축합니다. (3) 시스템 지시문과 가장 최근 턴은 항상 유지합니다. 사용 사례에 필요한 “메모리” 양과 균형을 맞추십시오.

시스템 / 시스템 지시문은 어디에 넣습니까?

OpenAI 호환 및 Anthropic에서는 대화의 앞부분에 넣습니다(호환 방식은 role:"system"를 사용하고, Anthropic은 최상위 system 필드 또는 첫 번째 메시지를 사용합니다). Gemini에서는 config.system_instruction를 사용하십시오. 시스템 지시문은 한 번만 설정하면 되므로 매 턴 다시 추가할 필요가 없습니다.

추론 모델의 thinking (reasoning_content)을 다시 전달해야 합니까?

아니오. thinking은 한 턴의 중간 산출물입니다. 이력에는 최종 content만 보관하십시오(Gemini의 경우 text만 보관합니다). thinking을 다시 전달하면 tokens를 낭비하고 일부 상위 시스템에서는 이를 거부합니다. function-calling에서의 Gemini thoughtSignature는 예외이며, 공식 SDK가 자동으로 처리합니다.

서버가 대화를 기억해서 이력을 다시 전송하지 않아도 됩니까?

APIYI에서는 이것이 권장되지 않습니다. OpenAI Responses의 previous_response_id는 게이트웨이를 통해 동작한다고 보장되지 않습니다(테스트 결과: 메모리 없음). 모든 곳에서 클라이언트 측 자체 관리 이력을 사용하십시오. 이것이 모든 모델에서 가장 안정적이고 일관적입니다.

기초

기본 API

이미지 API (공식)

동영상 API (공식)

멀티모달 이해 API

텍스트 API

핵심 원칙: 히스토리를 직접 유지

OpenAI 호환 모드(모델 전반에서 작동)

추론 모델의 기록 처리

OpenAI 네이티브 형식 (Responses API)

Gemini 네이티브 형식

Anthropic 네이티브 형식

네 가지 형식 비교

자주 묻는 질문

관련 링크

​핵심 원칙: 히스토리를 직접 유지

​OpenAI 호환 모드(모델 전반에서 작동)

​추론 모델의 기록 처리

​OpenAI 네이티브 형식 (Responses API)

​Gemini 네이티브 형식

​Anthropic 네이티브 형식

​네 가지 형식 비교

​자주 묻는 질문

​관련 링크

핵심 원칙: 히스토리를 직접 유지

OpenAI 호환 모드(모델 전반에서 작동)

추론 모델의 기록 처리

OpenAI 네이티브 형식 (Responses API)

Gemini 네이티브 형식

Anthropic 네이티브 형식

네 가지 형식 비교

자주 묻는 질문

관련 링크