This article is a technical commentary and implementation example created using AI. Although the code and procedures provided are based on primary sources, the author has not verified their operation on actual hardware. Behavior may vary depending on the environment and version.
The official OpenAI “Prompt engineering” guide explains the fundamental concepts for obtaining consistent output from large language models, as well as implementation methods using the API. This article organizes the main elements of prompt design, model selection, and how to give instructions as presented in the official guide.
What Can Be Confirmed from Official Information
Using the OpenAI API, you can generate text from prompts much like a chatbot. The generated text can take many forms, including code, mathematical formulas, structured JSON data, and natural language. Primary sources introduce implementation examples using the Responses API and Chat Completions API.
Response Structure and Retrieving Output
The response object from the API contains an array of content generated by the model.
Responses API: An array is stored in the
outputproperty of the response. This may contain not only messages, but also tool calls, data regarding reasoning tokens generated by reasoning models, and more. Therefore, the documentation explains that it is unsafe to simply specify the first element to extract text. Some official SDKs provide anoutput_textproperty that aggregates all text output into a single string, which can be used as a shortcut.Chat Completions API: An array is stored in the
choicesproperty of the response, which includes messages, finish reasons (finish_reason), and other details. It is also possible to return structured data in JSON format (Structured Outputs) as needed.
Model Choices and Characteristics
One of the important choices when using the API is deciding which model to use. Primary sources list the characteristics of the following model types:
Reasoning models: Generate an internal chain of thought to analyze the input prompt. They excel at understanding complex tasks and multi-step planning, but tend to be slower in processing and more expensive compared to general GPT models.
GPT models: Fast, cost-efficient, and highly intelligent, though providing more explicit instructions on how to achieve a task yields better results.
Larger and smaller models (such as mini and nano): Offer trade-offs between speed, cost, and intelligence. Larger models excel at understanding prompts and solving problems across diverse domains, while smaller models can be used faster and more cheaply. When in doubt for general text generation or prompt iteration tasks,
gpt-5.6is positioned as a strong default.Pinning model snapshots: To maintain behavioral consistency, pin production applications to a specific model snapshot (e.g.,
gpt-4.1-2025-04-14).Building test and evaluation suites: Create tests to measure prompt behavior so you can monitor performance during iterative work or when upgrading model versions.
instructionsparameter: Gives the model high-level instructions on response generation behavior, such as tone, goals, and examples of correct responses. Instructions specified with this parameter take precedence over prompts within theinputparameter.Message roles (developer / user, etc.): You can divide content by role within the input array to clearly distinguish and pass developer instructions or user inquiries. The commentary in the primary sources explains that specifying via the
instructionsparameter and explicitly specifying message structures withdeveloperoruserroles within theinputarray are conceptually equivalent.It is recommended to pin model versions in production environments to prevent unpredictable outputs.
When parsing responses, rather than relying solely on
output[0]orchoices[0], you should leverage the aggregation properties provided by the SDK or safely process the returned array structure.Because output results may differ even across different model families and snapshots, it is important to always run evaluations when making changes.
Basic Principles of Prompt Engineering
Prompt engineering is the process of writing effective instructions so that a model consistently generates content that meets requirements. Because the content generated by models is non-deterministic, obtaining desired outputs requires an approach that combines both art and science.
Two key recommendations are given when building applications:
Message Roles and Giving Instructions
Methods for giving instructions to the model at different privilege levels include using the instructions API parameter or utilizing message role values.
コメント