텍스트 생성 (Chat Completions)

개요

텍스트 생성(Chat Completions)은 APIYi 플랫폼의 핵심 기능 중 하나로, 지능형 대화와 텍스트 생성을 위해 400개 이상의 인기 AI 모델을 지원합니다. 통합된 OpenAI 호환 인터페이스를 통해 다음을 쉽게 구현할 수 있습니다.

지능형 대화: 챗봇과 가상 비서 구축
콘텐츠 생성: 글 작성, 창작 생성, 카피라이팅
코드 지원: 코드 생성, 디버깅, 리팩터링 제안
지식 Q&A: 질문 응답, 지식 검색, 정보 추출
역할극: 맞춤형 AI 캐릭터와 시나리오 시뮬레이션

OpenAI GPT-4, Claude, Gemini, DeepSeek, Qwen 및 400개 이상의 주류 모델을 하나의 API 키로 지원합니다.

빠른 시작

기본 대화 예시

Chat Completions API를 사용하는 간단한 단일 턴 대화:

from openai import OpenAI

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

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Tell me about the history of artificial intelligence"}
    ]
)

print(response.choices[0].message.content)

다중 턴 대화 예시

컨텍스트 인식 대화를 위해 messages 배열을 통해 대화 기록을 유지합니다:

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 professional Python programming assistant"},
    {"role": "user", "content": "How do I read a CSV file?"},
    {"role": "assistant", "content": "You can use pandas library's read_csv() function..."},
    {"role": "user", "content": "How do I filter specific columns?"}
]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages
)

print(response.choices[0].message.content)

핵심 파라미터

model (필수)

모델 이름을 지정합니다. 자세한 내용은 모델 정보를 참고하십시오.

model="gpt-4o"  # GPT-4 Omni
model="claude-sonnet-4.5"  # Claude Sonnet 4.5
model="gemini-3-pro-preview"  # Gemini 3 Pro
model="deepseek-chat"  # DeepSeek Chat

messages (필수)

role 및 content 필드를 포함하는 대화 메시지 배열입니다:

system

AI의 동작과 역할을 정의하는 시스템 프롬프트

user

사용자 입력을 나타내는 사용자 메시지

assistant

AI 응답을 나타내는 어시스턴트 메시지

messages = [
    {"role": "system", "content": "You are a friendly customer service assistant"},
    {"role": "user", "content": "I want to inquire about refunds"},
    {"role": "assistant", "content": "Sure, what issue did you encounter?"},
    {"role": "user", "content": "The product has quality issues"}
]

temperature (선택 사항)

출력의 무작위성을 제어하며, 범위는 0.0 ~ 2.0, 기본값은 1.0입니다:

0.0 ~ 0.3: 더 결정론적이고 일관적이며, 사실 기반 작업(번역, 요약, 코드 생성)에 적합합니다
0.7 ~ 1.0: 창의성과 정확성의 균형이 좋으며, 일상 대화에 적합합니다
1.0 ~ 2.0: 더 창의적이고 다양하며, 창작 글쓰기와 브레인스토밍에 적합합니다

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Write a poem about spring"}],
    temperature=1.2  # Increase creativity
)

max_tokens (선택 사항)

비용과 응답 길이를 제어하기 위해 생성되는 token의 최대 수를 제한합니다:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Describe AI in one sentence"}],
    max_tokens=50  # Limit output length
)

모델마다 token 가격이 다릅니다. 자세한 내용은 과금을 참고하십시오.

top_p (선택 사항)

Nucleus sampling 매개변수이며, 범위는 0.0 ~ 1.0입니다. 출력 다양성을 제어합니다:

낮은 값(예: 0.5): 더 집중되고 결정론적인 출력
높은 값(예: 0.9): 더 다양하고 무작위적인 출력

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Recommend some sci-fi movies"}],
    top_p=0.8
)

temperature 또는 top_p 중 하나만 조정하고, 둘 다 동시에 조정하지 않는 것이 권장됩니다.

stream (선택 사항)

스트리밍 출력을 활성화하여 결과를 token 단위로 반환하고, 사용자 경험을 향상시킵니다:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Write an article about artificial intelligence"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

고급 사용법

시스템 프롬프트

system 역할을 통해 AI의 동작, 역할, 지식 범위, 응답 스타일을 정의합니다:

messages = [
    {
        "role": "system",
        "content": """You are a professional legal advisor assistant.

Rules:
1. Provide accurate and professional legal advice
2. Use plain language to explain legal terms
3. Cite relevant laws when necessary
4. Avoid absolute conclusions, suggest consulting professional lawyers
5. Maintain a neutral and objective stance"""
    },
    {"role": "user", "content": "Can employment contracts be terminated at any time?"}
]

롤플레잉

특정 개성과 전문성을 가진 AI 어시스턴트를 생성합니다:

messages = [
    {
        "role": "system",
        "content": "You are an experienced Python developer with 10 years of experience. You excel at solving problems with concise code, prefer Pythonic approaches, and proactively identify potential issues in code."
    },
    {"role": "user", "content": "Help me write a quicksort algorithm"}
]

컨텍스트 관리

긴 대화에서는 모델 token 한도를 초과하지 않도록 컨텍스트 길이를 적절히 관리합니다:

def manage_context(messages, max_history=10):
    """Keep recent conversation history"""
    # Preserve system messages
    system_messages = [m for m in messages if m["role"] == "system"]
    # Keep recent N messages
    recent_messages = messages[-max_history:]

    return system_messages + recent_messages

# Usage example
messages = manage_context(messages, max_history=10)
response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages
)

JSON 모드 출력

일부 모델은 JSON 형식 출력을 강제로 지정하는 것을 지원합니다:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a data extraction assistant. Always return results in JSON format"},
        {"role": "user", "content": "Extract key information from this text: Zhang San, male, 30 years old, software engineer"}
    ],
    response_format={"type": "json_object"}
)

import json
result = json.loads(response.choices[0].message.content)
print(result)

모범 사례

1. 적합한 모델 선택

작업 요구 사항에 따라 가장 비용 효율적인 모델을 선택하십시오:

작업 유형	권장 모델	참고 사항
일상 대화	gpt-4o-mini, deepseek-chat	비용이 낮고 응답이 빠름
복잡한 추론	gpt-4o, claude-sonnet-4.5, gemini-3-pro-preview	성능이 뛰어나고 정확도가 높음
코드 생성	gpt-4o, deepseek-coder, claude-sonnet-4.5	전문적인 역량
창작 글쓰기	claude-sonnet-4.5, gpt-4o	유창한 문장력
다국어 번역	gemini-3-pro-preview, gpt-4o	여러 언어 지원

2. 프롬프트 최적화

좋은 프롬프트는 출력 품질을 크게 향상시킵니다:

명확한 작업

AI가 필요한 맥락과 함께 무엇을 해야 하는지 명확하게 설명하십시오

형식 지정

출력 형식, 길이, 어조 등을 정의하십시오

예시 제공

AI가 기대치를 이해하도록 입력-출력 예시를 제공하십시오

단계별로

복잡한 작업을 여러 단계로 나누십시오

# ❌ Poor prompt
"Write an article"

# ✅ Good prompt
"""Write a popular science article about AI applications in healthcare.

Requirements:
- Length: 800-1000 words
- Audience: General readers
- Structure: Introduction, Application Scenarios, Case Analysis, Future Outlook
- Tone: Professional but accessible
- Include 2-3 real-world cases"""

3. 비용 관리

매개변수를 현명하게 사용하여 API 비용을 줄이십시오:

# Set max_tokens to limit output length
response = client.chat.completions.create(
    model="gpt-4o-mini",  # Use more cost-effective model
    messages=messages,
    max_tokens=500,  # Limit maximum output
    temperature=0.7
)

{/* Regularly clean conversation history */}
if len(messages) > 20:
    messages = messages[-10:]  # Keep only recent 10 messages

4. 오류 처리

예외 처리를 추가하여 애플리케이션 안정성을 높이십시오:

from openai import OpenAI, OpenAIError
import time

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

def chat_with_retry(messages, max_retries=3):
    """Chat function with retry mechanism"""
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="gpt-4o",
                messages=messages
            )
            return response.choices[0].message.content
        except OpenAIError as e:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            else:
                raise

# Usage example
try:
    result = chat_with_retry(messages)
    print(result)
except OpenAIError as e:
    print(f"API call failed: {e}")

5. 스트리밍 출력 사용

긴 텍스트 생성의 경우 스트리밍 출력이 사용자 경험을 향상시킵니다:

def stream_chat(messages):
    """Streaming output example"""
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        stream=True
    )

    full_response = ""
    for chunk in response:
        if chunk.choices[0].delta.content:
            content = chunk.choices[0].delta.content
            print(content, end="", flush=True)
            full_response += content

    return full_response

자주 묻는 질문

token 수를 어떻게 계산합니까?

모델마다 서로 다른 토크나이저를 사용합니다. 추정을 위해 tiktoken 라이브러리를 사용하십시오:

import tiktoken

def count_tokens(text, model="gpt-4o"):
    """Estimate token count for text"""
    encoding = tiktoken.encoding_for_model(model)
    return len(encoding.encode(text))

# Usage example
text = "Hello, world!"
tokens = count_tokens(text)
print(f"Token count: {tokens}")

출력이 잘리는 이유는 무엇입니까?

가능한 이유는 다음과 같습니다:

max_tokens 한도에 도달함
모델의 컨텍스트 윈도우가 충분하지 않음
콘텐츠 안전 정책이 작동함

해결 방법은 다음과 같습니다:

max_tokens 매개변수를 늘리십시오
더 긴 컨텍스트 지원을 제공하는 모델을 선택하십시오
원인을 확인하려면 finish_reason 필드를 확인하십시오

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    max_tokens=2000  # Increase output length limit
)

finish_reason = response.choices[0].finish_reason
if finish_reason == "length":
    print("Output truncated due to length limit")
elif finish_reason == "content_filter":
    print("Output filtered due to content safety")

대화 메모리를 어떻게 구현합니까?

애플리케이션 레이어에서 대화 기록을 유지하십시오:

class ChatSession:
    def __init__(self, system_prompt=""):
        self.messages = []
        if system_prompt:
            self.messages.append({"role": "system", "content": system_prompt})

    def chat(self, user_message):
        """Send message and record conversation"""
        self.messages.append({"role": "user", "content": user_message})

        response = client.chat.completions.create(
            model="gpt-4o",
            messages=self.messages
        )

        assistant_message = response.choices[0].message.content
        self.messages.append({"role": "assistant", "content": assistant_message})

        return assistant_message

# Usage example
session = ChatSession(system_prompt="You are a friendly assistant")
print(session.chat("Hello"))
print(session.chat("What did I just say?"))  # AI can remember context

모델 정보

지원되는 모든 모델과 과금을 확인합니다

텍스트 임베딩

텍스트를 벡터 표현으로 변환합니다

​개요

​빠른 시작

​기본 대화 예시

​다중 턴 대화 예시

​핵심 파라미터

​model (필수)

​messages (필수)

system

user

assistant

​temperature (선택 사항)

​max_tokens (선택 사항)

​top_p (선택 사항)

​stream (선택 사항)

​고급 사용법

​시스템 프롬프트

​롤플레잉

​컨텍스트 관리

​JSON 모드 출력

​모범 사례

​1. 적합한 모델 선택

​2. 프롬프트 최적화

명확한 작업

형식 지정

예시 제공

단계별로

​3. 비용 관리

​4. 오류 처리

​5. 스트리밍 출력 사용

​자주 묻는 질문

​token 수를 어떻게 계산합니까?

​출력이 잘리는 이유는 무엇입니까?

​대화 메모리를 어떻게 구현합니까?

​관련 문서

모델 정보

텍스트 임베딩

개요

빠른 시작

기본 대화 예시

다중 턴 대화 예시

핵심 파라미터

model (필수)

messages (필수)

temperature (선택 사항)

max_tokens (선택 사항)

top_p (선택 사항)

stream (선택 사항)

고급 사용법

시스템 프롬프트

롤플레잉

컨텍스트 관리

JSON 모드 출력

모범 사례

1. 적합한 모델 선택

2. 프롬프트 최적화

3. 비용 관리

4. 오류 처리

5. 스트리밍 출력 사용

자주 묻는 질문

token 수를 어떻게 계산합니까?

출력이 잘리는 이유는 무엇입니까?

대화 메모리를 어떻게 구현합니까?

관련 문서