openai/openai-java

OpenAI Java SDK – 무엇인가

openai‑java 저장소는 OpenAI REST API용 공식 Java 클라이언트 라이브러리입니다. Java 애플리케이션이 HTTP 요청을 직접 만들 필요 없이 OpenAI 서비스(ChatGPT, DALL‑E, embeddings 등)와 통신할 수 있게 해줍니다. SDK는 인증, 요청 구성, 응답 파싱, 스트리밍, 비동기 실행을 처리하며 Amazon Bedrock 및 클라우드 네이티브 워크로드 ID 인증과도 통합됩니다.

얻는 방법

빌드에 라이브러리를 추가하세요 – README에는 최신 버전(작성 시점 기준 4.81.0)이 나와 있습니다:

Gradle (Kotlin DSL)

implementation("com.openai:openai-java:4.81.0")

Maven

<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>4.81.0</version>
</dependency>

SDK는 Java 8 이상이 필요합니다.

빠른 시작 예제

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.ChatModel;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

// 환경 변수에서 API 키 등을 읽습니다.
OpenAIClient client = OpenAIOkHttpClient.fromEnv();

ResponseCreateParams params = ResponseCreateParams.builder()
        .input("Say this is a test")
        .model(ChatModel.GPT_5_2)
        .build();

Response response = client.responses().create(params);
System.out.println(response);

동일한 패턴이 기존 Chat Completions 엔드포인트에도 적용됩니다:

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .addUserMessage("Say this is a test")
    .model(ChatModel.GPT_5_2)
    .build();
ChatCompletion chat = client.chat().completions().create(params);
System.out.println(chat);

주요 기능

기능	제공 내용
동기 및 비동기 API	차단 호출은 `client`를 호출하고, `CompletableFuture` 기반 비차단 호출은 `client.async()`를 호출합니다.
스트리밍 지원	`createStreaming` 메서드를 통해 도착하는 대로 부분 결과를 수신하며, 보조 클래스(`ChatCompletionAccumulator`)로 최종 객체를 재조립할 수 있습니다.
불변 모델 객체	모든 요청/응답 객체는 빌더로 생성되며 생성 후 불변이므로 스레드 간 공유에 안전합니다.
구성 가능한 인증	API 키는 환경 변수, 시스템 속성 또는 워크로드 ID 메커니즘(Kubernetes 서비스 계정 토큰, Azure Managed Identity, GCP ID 토큰, X.509 클라이언트 인증서)으로 제공할 수 있습니다.
Amazon Bedrock 통합	선택적 `openai-java-bedrock` 아티팩트를 사용하면 일반 AWS 자격 증명으로 Bedrock에서 호스팅되는 OpenAI 호환 모델을 호출할 수 있습니다.
클라이언트 풀링	SDK는 단일 `OpenAIClient`(연결 풀 + 스레드 풀)를 재사용합니다. README는 애플리케이션당 클라이언트를 하나만 생성할 것을 권장합니다.
세밀한 옵션	`withOptions`를 사용하여 기본 풀을 유지하면서 설정(기본 URL, 재시도 횟수 등)을 일시적으로 조정할 수 있습니다.
Java 중심의 사용성	빌더, 타입 안전 열거형(`ChatModel.GPT_5_2`), 포괄적인 Javadoc으로 API가 Java 개발자에게 네이티브하게 느껴집니다.

구성 세부 사항

인증은 세 가지 방법으로 제공할 수 있습니다:

환경 변수 – OPENAI_API_KEY, OPENAI_ORG_ID, OPENAI_PROJECT_ID 등
시스템 속성 – openai.apiKey, openai.orgId, … (속성이 환경 변수보다 우선함)
프로그래매틱 빌더 – OpenAIOkHttpClient.builder().apiKey("…").adminApiKey("…").build();

모든 옵션은 README의 표에 나열되어 있으며, baseUrl은 기본적으로 https://api.openai.com/v1입니다.

고급 사용 사례

워크로드 ID – SDK는 Kubernetes, Azure 또는 GCP의 단기 토큰을 OpenAI 액세스 토큰으로 교환할 수 있어 장기 API 키를 저장할 필요가 없습니다.
X.509 상호 TLS – 규제가 많은 환경에서 클라이언트 인증서와 개인 키를 제공할 수 있으며, SDK는 상호 TLS 채널을 통해 토큰 교환을 수행합니다.
스트리밍용 사용자 지정 Executor – 비동기 스트리밍에 사용되는 기본 스레드 풀을 subscribe 또는 클라이언트 빌더의 streamHandlerExecutor에 사용자 지정 Executor를 전달하여 재정의할 수 있습니다.

더 많은 정보

전체 Javadoc – https://javadoc.io/doc/com.openai/openai-java
예제 코드 – 실행 가능한 채팅, 스트리밍, 비동기 및 워크로드 ID 사용 데모는 openai-java-example 모듈을 참조하세요.
기여 가이드 – CONTRIBUTING.md에 개발 JDK 설정, 린트 실행, PR 제출 방법이 설명되어 있습니다.
버전 지원 정책 – docs/version-support-policy.md는 각 아티팩트가 지원하는 Java 버전을 나열합니다.

요약

openai-java는 OpenAI HTTP API를 관용적인 Java 객체로 추상화하는 프로덕션 준비가 된 공식 유지 관리 Java SDK입니다. 동기, 비동기 및 스트리밍 호출을 지원하고 표준 API 키 또는 클라우드 네이티브 워크로드 ID 토큰과 함께 작동하며 Amazon Bedrock에서 OpenAI 호환 모델을 호출할 수도 있습니다. Maven/Gradle 프로젝트에 추가하고 키를 구성한 후 몇 줄의 코드로 GPT‑5 스타일 모델에 프롬프트를 보내기 시작하세요.