프롬프트 엔지니어링

OpenAI API에서는 대규모 언어 모델에 프롬프트를 보내 텍스트를 생성할 수 있습니다. ChatGPT를 사용할 때와 같은 방식입니다. 모델은 코드, 수식, 구조화된 JSON 데이터, 사람이 쓴 듯한 자연스러운 글 등 거의 모든 종류의 텍스트 응답을 생성할 수 있습니다.

다음은 Responses API를 사용하는 간단한 예시입니다.

간단한 프롬프트로 텍스트 생성하기

JavaScript

1
2
3
4
5
6
7
8
9import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: "Write a one-sentence bedtime story about a unicorn.",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="Write a one-sentence bedtime story about a unicorn.",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()

	resp, err := client.Responses.New(context.TODO(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Say this is a test")},
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Println(resp.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

public class Main {
  public static void main(String[] args) {
    OpenAIClient client = OpenAIOkHttpClient.fromEnv();

    ResponseCreateParams params =
        ResponseCreateParams.builder().input("Say this is a test").model("gpt-6-astra").build();

    Response response = client.responses().create(params);
    response.output().stream()
        .flatMap(item -> item.message().stream())
        .flatMap(message -> message.content().stream())
        .flatMap(content -> content.outputText().stream())
        .forEach(outputText -> System.out.println(outputText.text()));
  }
}

1
2
3
4
5
6
7
8
9
10
11
12using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

ResponseResult response = await client.CreateResponseAsync(
    "gpt-6-astra",
    "Say 'this is a test.'"
);

Console.WriteLine($"[ASSISTANT]: {response.GetOutputText()}");

1
2
3
4
5
6
7
8
9
10require "openai"

openai = OpenAI::Client.new

response = openai.responses.create(
  model: "gpt-6-astra",
  input: "Write a one-sentence bedtime story about a unicorn."
)

puts(response.output_text)

1
2
3
4
5openai responses create \
  --model "gpt-6-astra" \
  --input "Write a one-sentence bedtime story about a unicorn." \
  --raw-output \
  --transform 'output.#(type=="message").content.0.text'

1
2
3
4
5
6
7curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6-astra",
        "input": "Write a one-sentence bedtime story about a unicorn."
    }'

응답의 output 속성에는 모델이 생성한 콘텐츠가 배열로 담깁니다. 이 예시에서는 다음과 같이 출력 항목이 하나뿐입니다.

1234567891011121314[
  {
    "id": "msg_67b73f697ba4819183a15cc17d011509",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "Under the soft glow of the moon, Luna the unicorn danced through fields of twinkling stardust, leaving trails of dreams for every child asleep.",
        "annotations": []
      }
    ]
  }
]

output 배열에는 항목이 여러 개 들어가는 경우가 많습니다. 도구 호출, 추론 모델이 생성한 추론 토큰에 관한 데이터 등 다양한 항목이 포함될 수 있습니다. 따라서 모델이 출력한 텍스트가 항상 output[0].content[0].text에 있다고 가정하면 안 됩니다.

일부 공식 SDK는 모델 응답에 output_text 속성을 제공합니다. 이 속성은 모델이 출력한 모든 텍스트를 하나의 문자열로 모아 주므로 텍스트 출력에 간편하게 접근할 수 있습니다.

일반 텍스트 외에도 모델이 JSON 형식의 구조화된 데이터를 반환하도록 할 수 있습니다. 이 기능을 구조화된 출력값이라고 합니다.

다음은 Chat Completions API를 사용하는 간단한 예시입니다.

간단한 프롬프트로 텍스트 생성하기

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14import OpenAI from "openai";
const client = new OpenAI();

const completion = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [
    {
      role: "user",
      content: "Write a one-sentence bedtime story about a unicorn.",
    },
  ],
});

console.log(completion.choices[0].message.content);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {
            "role": "user",
            "content": "Write a one-sentence bedtime story about a unicorn.",
        }
    ],
)

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()

	completion, err := client.Chat.Completions.New(
		context.Background(),
		openai.ChatCompletionNewParams{
			Model: "gpt-6-astra",
			Messages: []openai.ChatCompletionMessageParamUnion{
				openai.UserMessage("Write a one-sentence bedtime story about a unicorn."),
			},
		},
	)
	if err != nil {
		panic(err)
	}

	fmt.Println(completion.Choices[0].Message.Content)
}

1
2
3
4
5
6
7
8
9
10
11
12
13import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

ChatCompletionCreateParams params =
    ChatCompletionCreateParams.builder()
        .model("gpt-6-astra")
        .addUserMessage("Write a one-sentence bedtime story about a unicorn.")
        .build();

client.chat().completions().create(params).choices().stream()
    .flatMap(choice -> choice.message().content().stream())
    .forEach(System.out::println);

1
2
3
4
5
6
7
8
9
10
11using OpenAI.Chat;

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
string model = "gpt-6-astra";
ChatClient client = new(model, key);

ChatCompletion completion = await client.CompleteChatAsync(
    new UserChatMessage("Write a one-sentence bedtime story about a unicorn.")
);

Console.WriteLine(completion.Content[0].Text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"

client = OpenAI::Client.new
completion = client.chat.completions.create(
  model: "gpt-6-astra",
  messages: [
    {
      role: :user,
      content: "Write a one-sentence bedtime story about a unicorn."
    }
  ]
)

puts(completion.choices.fetch(0).message.content)

1
2
3
4
5
6
7
8
9
10
11
12curl "https://api.openai.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-5.5",
        "messages": [
            {
                "role": "user",
                "content": "Write a one-sentence bedtime story about a unicorn."
            }
        ]
    }'

응답의 choices 속성에는 모델이 생성한 콘텐츠가 배열로 담깁니다. 이 예시에서는 다음과 같이 출력 항목이 하나뿐입니다.

123456789101112[
  {
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Under the soft glow of the moon, Luna the unicorn danced through fields of twinkling stardust, leaving trails of dreams for every child asleep.",
      "refusal": null
    },
    "logprobs": null,
    "finish_reason": "stop"
  }
]

일반 텍스트 외에도 모델이 JSON 형식의 구조화된 데이터를 반환하도록 할 수 있습니다. 이 기능을 구조화된 출력값이라고 합니다.

모델 선택하기

API로 콘텐츠를 생성할 때는 먼저 어떤 모델을 사용할지 정해야 합니다. 위 코드 예시에서는 model 매개변수로 모델을 지정합니다. 사용 가능한 모델 전체 목록을 확인하세요. 텍스트 생성용 모델을 선택할 때는 다음 사항을 고려하세요.

추론 모델은 내부 추론 과정을 통해 입력 프롬프트를 분석하며, 복잡한 작업을 이해하고 여러 단계에 걸친 계획을 세우는 데 뛰어납니다. 일반적으로 GPT 모델보다 느리고 사용 비용이 높습니다.
GPT 모델은 빠르고 비용 효율적이며 성능이 뛰어납니다. 작업 수행 방법을 구체적으로 지시하면 더 좋은 결과를 얻을 수 있습니다.
대형 모델과 소형 모델(mini 또는 nano)은 속도, 비용, 문제 해결 능력 면에서 각각 장단점이 있습니다. 대형 모델은 프롬프트를 이해하고 다양한 분야의 문제를 해결하는 데 더 뛰어나며, 소형 모델은 일반적으로 더 빠르고 사용 비용이 낮습니다.

어떤 모델을 선택할지 확신이 서지 않는다면 범용 텍스트 생성과 프롬프트 개선에는 gpt-6-astra부터 사용해 보세요.

프롬프트 엔지니어링

프롬프트 엔지니어링은 모델이 요구 사항에 맞는 콘텐츠를 일관되게 생성하도록 효과적인 지침을 작성하는 과정입니다.

같은 입력에도 모델이 생성하는 콘텐츠는 달라질 수 있습니다. 따라서 원하는 출력을 얻는 프롬프트를 작성하려면 체계적인 접근과 감각이 모두 필요합니다. 여러 기법과 모범 사례를 적용하면 꾸준히 좋은 결과를 얻을 수 있습니다.

메시지 역할을 사용하는 것처럼 모든 모델에 통하는 프롬프트 엔지니어링 기법도 있습니다. 하지만 추론 모델과 GPT 모델처럼 유형이 다르면 최적의 결과를 내는 프롬프트 작성 방식도 달라질 수 있습니다. 같은 모델 제품군에서도 스냅샷에 따라 결과가 달라질 수 있습니다. 따라서 복잡한 애플리케이션을 개발할 때는 다음 두 가지를 적극 권장합니다.

프로덕션 애플리케이션이 일관되게 동작하도록 특정 모델 스냅샷(예: gpt-4.1-2025-04-14)을 지정해 사용하세요.
프롬프트가 어떻게 동작하는지 측정하는 테스트와 평가 모음을 마련하세요. 프롬프트를 개선하거나 모델 버전을 변경 또는 업그레이드할 때 성능을 추적할 수 있습니다.

이제 프롬프트를 구성하는 데 사용할 수 있는 도구와 기법을 살펴보겠습니다.

메시지 역할과 지침 준수

모델에 전달하는 지침의 권한 수준은 instructions API 매개변수나 메시지 역할로 구분할 수 있습니다.

instructions 매개변수는 모델이 응답을 생성할 때 따를 전반적인 지침을 제공합니다. 여기에는 어조, 목표, 올바른 응답의 예시 등을 포함할 수 있습니다. 이 방식으로 전달한 지침은 input 매개변수에 담긴 프롬프트보다 우선합니다.

지침을 제공해 텍스트 생성하기

JavaScript

1
2
3
4
5
6
7
8
9
10
11import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "low" },
  instructions: "Talk like a pirate.",
  input: "Are semicolons optional in JavaScript?",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "low"},
    instructions="Talk like a pirate.",
    input="Are semicolons optional in JavaScript?",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:        "gpt-6-astra",
		Instructions: openai.String("Talk like a pirate."),
		Reasoning: responses.ReasoningParam{
			Effort: responses.ReasoningEffortLow,
		},
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("Are semicolons optional in JavaScript?"),
		},
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.ResponseCreateParams;

String semicolonsDevMsg = "Talk like a pirate.";

String semicolonsPrompt = "Are semicolons optional in JavaScript?";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(semicolonsPrompt)
        .instructions(semicolonsDevMsg)
        .reasoning(Reasoning.builder().effort(ReasoningEffort.LOW).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new()
{
    Model = "gpt-6-astra",
    Instructions = "Talk like a pirate.",
    ReasoningOptions = new ResponseReasoningOptions
    {
        ReasoningEffortLevel = ResponseReasoningEffortLevel.Low,
    },
};
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("Are semicolons optional in JavaScript?")
);

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  instructions: "Talk like a pirate.",
  reasoning: { effort: :low },
  input: "Are semicolons optional in JavaScript?"
)

puts(response.output_text)

1
2
3
4
5
6
7
8
9curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6-astra",
        "reasoning": {"effort": "low"},
        "instructions": "Talk like a pirate.",
        "input": "Are semicolons optional in JavaScript?"
    }'

위 예시는 input 배열에 다음과 같은 입력 메시지를 넣는 방식과 대체로 같습니다.

역할이 다른 메시지로 텍스트 생성하기

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "low" },
  input: [
    {
      role: "developer",
      content: "Talk like a pirate.",
    },
    {
      role: "user",
      content: "Are semicolons optional in JavaScript?",
    },
  ],
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "low"},
    input=[
        {"role": "developer", "content": "Talk like a pirate."},
        {"role": "user", "content": "Are semicolons optional in JavaScript?"},
    ],
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Reasoning: responses.ReasoningParam{
			Effort: responses.ReasoningEffortLow,
		},
		Input: responses.ResponseNewParamsInputUnion{
			OfInputItemList: responses.ResponseInputParam{
				responses.ResponseInputItemParamOfMessage(
					"Talk like a pirate.",
					responses.EasyInputMessageRoleDeveloper,
				),
				responses.ResponseInputItemParamOfMessage(
					"Are semicolons optional in JavaScript?",
					responses.EasyInputMessageRoleUser,
				),
			},
		},
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import java.util.List;

String semicolonsDevMsg = "Talk like a pirate.";

String semicolonsPrompt = "Are semicolons optional in JavaScript?";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(
            ResponseCreateParams.Input.ofResponse(
                List.of(
                    ResponseInputItem.ofEasyInputMessage(
                        EasyInputMessage.builder()
                            .role(EasyInputMessage.Role.DEVELOPER)
                            .content(semicolonsDevMsg)
                            .build()),
                    ResponseInputItem.ofEasyInputMessage(
                        EasyInputMessage.builder()
                            .role(EasyInputMessage.Role.USER)
                            .content(semicolonsPrompt)
                            .build()))))
        .reasoning(Reasoning.builder().effort(ReasoningEffort.LOW).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new()
{
    Model = "gpt-6-astra",
    ReasoningOptions = new ResponseReasoningOptions
    {
        ReasoningEffortLevel = ResponseReasoningEffortLevel.Low,
    },
};
options.InputItems.Add(
    ResponseItem.CreateDeveloperMessageItem("Talk like a pirate.")
);
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("Are semicolons optional in JavaScript?")
);

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  reasoning: { effort: :low },
  input: [
    {
      role: :developer,
      content: "Talk like a pirate."
    },
    {
      role: :user,
      content: "Are semicolons optional in JavaScript?"
    }
  ]
)

puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6-astra",
        "reasoning": {"effort": "low"},
        "input": [
            {
                "role": "developer",
                "content": "Talk like a pirate."
            },
            {
                "role": "user",
                "content": "Are semicolons optional in JavaScript?"
            }
        ]
    }'

instructions 매개변수는 현재 응답 생성 요청에만 적용됩니다. 대화 상태를 관리할 때 previous_response_id 매개변수를 사용하더라도 이전 턴의 instructions는 현재 컨텍스트에 포함되지 않습니다.

모델에 전달하는 지침(프롬프트)의 권한 수준은 메시지 역할로 구분할 수 있습니다.

역할이 다른 메시지로 텍스트 생성하기

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import OpenAI from "openai";
const client = new OpenAI();

const completion = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages: [
    {
      role: "developer",
      content: "Talk like a pirate.",
    },
    {
      role: "user",
      content: "Are semicolons optional in JavaScript?",
    },
  ],
});

console.log(completion.choices[0].message);

1
2
3
4
5
6
7
8
9
10
11
12
13
14from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-6-astra",
    reasoning_effort="low",
    messages=[
        {"role": "developer", "content": "Talk like a pirate."},
        {"role": "user", "content": "Are semicolons optional in JavaScript?"},
    ],
)

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()

	completion, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
		Model: "gpt-6-astra",
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.DeveloperMessage("Talk like a pirate."),
			openai.UserMessage("Are semicolons optional in JavaScript?"),
		},
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(completion.Choices[0].Message.Content)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

String semicolonsDevMsg = "Talk like a pirate.";

String semicolonsPrompt = "Are semicolons optional in JavaScript?";

ChatCompletionCreateParams params =
    ChatCompletionCreateParams.builder()
        .model("gpt-6-astra")
        .addDeveloperMessage(semicolonsDevMsg)
        .addUserMessage(semicolonsPrompt)
        .build();

client.chat().completions().create(params).choices().stream()
    .flatMap(choice -> choice.message().content().stream())
    .forEach(System.out::println);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15using OpenAI.Chat;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
string model = "gpt-6-astra";
ChatClient client = new(model, key);

ChatCompletion completion = await client.CompleteChatAsync(
    [
        new DeveloperChatMessage("Talk like a pirate."),
        new UserChatMessage("Are semicolons optional in JavaScript?"),
    ]
);

Console.WriteLine(completion.Content[0].Text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18require "openai"

client = OpenAI::Client.new
completion = client.chat.completions.create(
  model: "gpt-6-astra",
  messages: [
    {
      role: :developer,
      content: "Talk like a pirate."
    },
    {
      role: :user,
      content: "Are semicolons optional in JavaScript?"
    }
  ]
)

puts(completion.choices.fetch(0).message.content)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16curl "https://api.openai.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6-astra",
        "messages": [
            {
                "role": "developer",
                "content": "Talk like a pirate."
            },
            {
                "role": "user",
                "content": "Are semicolons optional in JavaScript?"
            }
        ]
    }'

OpenAI 모델 사양은 모델이 메시지의 역할에 따라 우선순위를 어떻게 정하는지 설명합니다.

`developer`	`user`	`assistant`
`developer` 메시지는 애플리케이션 개발자가 제공하는 지침으로, `user` 메시지보다 우선합니다.	`user` 메시지는 최종 사용자가 제공하는 지침으로, `developer` 메시지보다 우선순위가 낮습니다.	모델이 생성한 메시지의 역할은 `assistant`입니다.

여러 턴에 걸친 대화에는 이런 유형의 메시지가 여러 개 포함될 수 있으며, 개발자와 모델이 제공하는 다른 유형의 콘텐츠도 함께 들어갈 수 있습니다. 자세한 내용은 대화 상태 관리를 참고하세요.

developer 메시지와 user 메시지의 관계는 프로그래밍 언어에서 함수와 인수의 관계에 비유할 수 있습니다.

developer 메시지는 함수 정의처럼 시스템의 규칙과 비즈니스 로직을 제공합니다.
user 메시지는 함수의 인수처럼 developer 메시지의 지침을 적용할 입력과 설정을 제공합니다.

코드에서 프롬프트 버전 관리하기

재사용 가능한 프롬프트 객체를 만드는 대신 프로덕션 프롬프트를 애플리케이션 코드에 저장하세요. 프롬프트를 코드로 관리하면 타입이 지정된 입력, 코드 리뷰, 테스트, 기존 배포 절차를 활용해 모델 동작을 변경할 수 있습니다.

OpenAI API의 재사용 가능한 프롬프트 객체는 사용 중단 예정(deprecated)입니다. 2026년 6월 3일부터 프롬프트 객체 생성 기능의 비중이 줄어들며, v1/prompts는 2026년 11월 30일에 종료될 예정입니다. 최신 일정은 사용 중단 일정 페이지에서 확인하세요.

새로 프롬프트를 설계할 때는 다음과 같이 진행하세요.

프롬프트를 구성하는 코드는 해당 기능의 코드와 가까운 곳에 작은 모듈로 두세요.
고객 데이터, 파일, 작업 옵션처럼 요청마다 달라지는 값에는 타입이 지정된 함수 인수나 스키마를 사용하세요.
생성한 instructions와 input을 Responses API에 직접 전달하세요.
프로덕션 프롬프트를 변경하기 전에 대표적인 테스트 픽스처, 테스트, 평가 항목을 추가하세요.
기존 배포 시스템으로 프롬프트 변경 사항을 배포하세요. 단계적으로 릴리스해야 한다면 기능 플래그나 설정을 활용하세요.

이미 프롬프트 ID나 버전으로 저장된 프롬프트를 호출하고 있다면 프롬프트 객체 마이그레이션 가이드에 따라 해당 프롬프트를 코드로 옮기세요.

Markdown과 XML로 메시지 구성하기

developer 메시지와 user 메시지를 작성할 때 Markdown 서식과 XML 태그를 함께 사용하면 모델이 프롬프트와 컨텍스트 데이터에서 각 부분의 경계를 파악하기 쉽습니다.

Markdown 제목과 목록은 프롬프트를 여러 섹션으로 구분하고 모델에 계층 구조를 전달하는 데 유용합니다. 개발 중에 프롬프트를 읽기도 한결 쉬워집니다. XML 태그로는 참고 문서와 같은 개별 콘텐츠의 시작과 끝을 표시할 수 있습니다. XML 속성에 프롬프트 콘텐츠의 메타데이터를 정의해 두면 지침에서 이를 참조할 수 있습니다.

개발자 메시지는 일반적으로 다음 섹션을 아래 순서로 구성합니다. 가장 효과적인 내용과 순서는 사용하는 모델에 따라 달라질 수 있습니다.

역할: 어시스턴트의 목적, 의사소통 방식, 전반적인 목표를 설명하세요.
지침: 원하는 응답을 어떻게 생성할지 모델에 안내하세요. 어떤 규칙을 따라야 하나요? 무엇을 해야 하고 무엇을 절대 해서는 안 되나요? 사용 사례에 따라 모델이 사용자 정의 함수를 호출하는 방법 등 여러 하위 섹션을 둘 수 있습니다.
예시: 가능한 입력과 그에 대해 모델이 생성해야 할 출력을 함께 제시하세요.
컨텍스트: 모델이 응답을 생성하는 데 필요한 추가 정보를 제공하세요. 학습 데이터에 없는 비공개 데이터나 독점 데이터, 해당 요청과 특히 관련이 깊다고 판단한 데이터 등이 여기에 해당합니다. 생성 요청마다 필요한 컨텍스트가 달라질 수 있으므로 보통 프롬프트 끝부분에 배치하는 것이 좋습니다.

다음 예시는 Markdown과 XML 태그를 사용해 developer 메시지를 섹션별로 나누고 지침을 뒷받침하는 예시를 포함하는 방법을 보여 줍니다.

코드 생성을 위한 개발자 메시지

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24# Identity

You are coding assistant that helps enforce the use of snake case
variables in JavaScript code, and writing code that will run in
Internet Explorer version 6.

# Instructions

* When defining variables, use snake case names (e.g. my_variable)
  instead of camel case names (e.g. myVariable).
* To support old browsers, declare variables using the older
  "var" keyword.
* Do not give responses with Markdown formatting, just return
  the code as requested.

# Examples

<user_query>
How do I declare a string variable for a first name?
</user_query>

<assistant_response>
var first_name = "Anna";
</assistant_response>

API로 코드 생성 프롬프트 보내기

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13import fs from "fs/promises";
import OpenAI from "openai";
const client = new OpenAI();

const instructions = await fs.readFile("fixtures/prompt.txt", "utf-8");

const response = await client.responses.create({
  model: "gpt-6-astra",
  instructions,
  input: "How would I declare a variable for a last name?",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14from openai import OpenAI

client = OpenAI()

with open("prompt.txt", "r", encoding="utf-8") as f:
    instructions = f.read()

response = client.responses.create(
    model="gpt-6-astra",
    instructions=instructions,
    input="How would I declare a variable for a last name?",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()

	instructions, err := os.ReadFile("prompt.txt")
	if err != nil {
		panic(err)
	}

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:        "gpt-6-astra",
		Instructions: openai.String(string(instructions)),
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("How would I declare a variable for a last name?"),
		},
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .instructions(
            "You are a coding assistant. Answer with concise JavaScript examples and use semicolons.")
        .input("How would I declare a variable for a last name?")
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

string instructions = await File.ReadAllTextAsync("prompt.txt");
CreateResponseOptions options = new()
{
    Model = "gpt-6-astra",
    Instructions = instructions,
};
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("How would I declare a variable for a last name?")
);

ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11require "openai"

client = OpenAI::Client.new
instructions = File.read(File.join(__dir__, "prompt.txt"))
response = client.responses.create(
  model: "gpt-6-astra",
  instructions: instructions,
  input: "How would I declare a variable for a last name?"
)

puts(response.output_text)

1
2
3
4
5
6
7
8curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "instructions": "'"$(< prompt.txt)"'",
    "input": "How would I declare a variable for a last name?"
  }'

프롬프트 캐싱으로 비용과 지연 시간 줄이기

메시지를 구성할 때 여러 API 요청에서 반복해서 사용할 콘텐츠는 프롬프트 앞부분에 두세요. 또한 Chat Completions나 Responses에 보내는 JSON 요청 본문에서도 이 콘텐츠가 담긴 API 매개변수를 앞쪽에 배치하세요. 이렇게 하면 프롬프트 캐싱을 활용해 비용과 지연 시간을 최대한 줄일 수 있습니다.

퓨샷 학습

퓨샷 학습은 프롬프트에 몇 가지 입력과 출력 예시를 넣어 대규모 언어 모델이 새로운 작업을 수행하도록 유도하는 방법입니다. 모델을 별도로 파인튜닝할 필요 없이 모델이 예시에서 패턴을 파악해 프롬프트에 적용합니다. 예시를 작성할 때는 다양한 입력과 각 입력에 대해 원하는 출력을 함께 보여 주세요.

일반적으로 예시는 API 요청의 developer 메시지에 포함합니다. 다음 developer 메시지는 고객 서비스 리뷰를 긍정 또는 부정으로 분류하는 방법을 예시로 보여 줍니다.

# 역할

당신은 짧은 제품 리뷰에 Positive, Negative, Neutral 중 하나의 레이블을 붙이는 어시스턴트입니다.

# 지침

* 응답에는 서식이나 설명을 덧붙이지 말고 단어 하나만 출력하세요.
* 주어진 제품 리뷰에 나타난 감정에 따라 반드시 "Positive", "Negative", "Neutral" 중 하나로 응답하세요.

# 예시

<product_review id="example-1">
I absolutely love this headphones — sound quality is amazing!
</product_review>

<assistant_response id="example-1">
Positive
</assistant_response>

<product_review id="example-2">
Battery life is okay, but the ear pads feel cheap.
</product_review>

<assistant_response id="example-2">
Neutral
</assistant_response>

<product_review id="example-3">
Terrible customer service, I'll never buy from them again.
</product_review>

<assistant_response id="example-3">
Negative
</assistant_response>

최신 모델용 프롬프트 작성하기

gpt-6-astra 같은 GPT 모델은 작업에 필요한 로직과 데이터를 프롬프트에 명시하고 정확한 지침을 제공할 때 더 좋은 결과를 냅니다. 최신 모델을 효과적으로 활용하려면 먼저 최신 프롬프트 작성 가이드를 살펴보세요.

GPT-6 Astra prompting guide

최신 지침과 실용적인 예시, 마이그레이션 시 참고 사항을 살펴보고 최신 모델에 맞는 프롬프트를 작성하세요.

추론 모델용 프롬프트 작성하기

추론 모델용 프롬프트를 작성할 때는 GPT 모델과의 차이를 고려해야 합니다. 일반적으로 추론 모델은 작업의 큰 방향만 제시해도 더 좋은 결과를 냅니다. 반면 GPT 모델에는 매우 구체적인 지침이 효과적입니다.

추론 모델과 GPT 모델의 차이는 동료의 경력에 비유할 수 있습니다.

추론 모델은 경험이 풍부한 동료와 같습니다. 목표를 알려 주면 세부적인 해결 방법은 맡길 수 있습니다.
GPT 모델은 경력이 짧은 동료와 같습니다. 어떤 결과물을 어떻게 만들어야 하는지 명확히 지시할 때 가장 좋은 성과를 냅니다.

추론 모델 사용 시 권장 사항은 추론 모델 모범 사례 가이드를 참고하세요.

다음 단계

텍스트 입력과 출력의 기본을 익혔다면 다음 자료를 살펴보세요.

Playground에서 프롬프트 만들기

Playground에서 프롬프트를 작성하고 반복해서 개선해 보세요.

구조화된 출력값으로 JSON 데이터 생성하기

모델이 출력하는 JSON 데이터가 JSON 스키마를 따르도록 하세요.

전체 API 레퍼런스

API 레퍼런스에서 텍스트 생성에 사용할 수 있는 모든 옵션을 확인하세요.

기타 자료

더 많은 아이디어는 OpenAI Cookbook에서 찾아보세요. 예제 코드와 함께 다음과 같은 외부 자료 링크를 제공합니다.

추천

시작하기

핵심 개념

SDK 및 CLI

클라우드 제공업체

자료

레거시 API

모델 선택하기

텍스트 및 코드

프롬프트 작성

추론

이미지

실시간 처리 및 오디오

특화 모델

Agents API

Agents SDK

ChatKit

검색 및 정보 조회

도구와 데이터 연결하기

도구를 활용한 워크플로우 구축하기

컴퓨터 및 코드

미디어

GPT-Live

Realtime API

음성 기능 개발

연결

오디오 처리

서비스 출시하기

성능 및 품질

평가

비용 및 처리량

안전 및 거버넌스

인프라 및 접근 권한

운영

핵심 개념

기획

개발

테스트 및 게시

전환 명세

가이드

자료

사용자 식별

ChatGPT 요금제 사용량

가이드

파일 업로드

API

성과 측정

광고주 API

API 레퍼런스

시작하기

시작하기

기초

둘러보기

지원 플랫폼

릴리스

워크플로우

주요 기능

Sites

dot

ChatGPT 스페이스

레퍼런스

맞춤 설정

설정 파일

에이전트 설정

ChatGPT와 Codex 확장하기

Linux

Windows

개발 워크플로우

확장 및 자동화

환경

Codex Cloud

Codex로 개발하기

서드 파티 통합

레퍼런스

권한

Codex Security

사이버 안전

시작하기

기능 설정

ID 및 액세스