2026/09/07

GPT-6 Astra API 마이그레이션 가이드

모델 발견, Responses API 요청, 추론 제어, 도구 검증, 승인 기준, 롤백 계획을 통해 GPT-6 Astra로 안전하게 마이그레이션합니다.

가장 안전한 GPT-6 Astra API 마이그레이션은 모델 이름에 대한 찾기와 바꾸기가 아니라 돌이킬 수 있는 설정 변경입니다. 프로덕션 API 키가 /v1/models에서 gpt-6-astra를 반환하는지 확인하고, 도구를 사용하는 요청을 Responses API로 옮기고, 검증을 통과하는 가장 낮은 추론 수준부터 시작한 다음, 모델이 거부하는 매개변수를 제거하고 canary 세트가 수락 기준을 충족할 때까지 이전 경로를 유지합니다.^[1]^[2]

이 가이드는 마이그레이션 예제에 OpenAI의 직접 API 계약을 사용합니다. OpenAI 호환 게이트웨이는 와이어 모델 ID가 같아도 다른 엔드포인트 및 매개변수 부분 집합을 노출할 수 있습니다. 해당 게이트웨이의 라이브 카탈로그와 문서를 별도로 확인하세요.

빠른 답변

프로덕션 키가 gpt-6-astra를 발견할 수 있는지 확인하세요. 발표는 자격이 있는지 확인하는 것이 아닙니다.
도구 호출을 Responses API로 옮기고 기존의 none 또는 minimal 추론을 low로 매핑합니다.^[1]^[2]
첫 요청 전에 지원되지 않는 샘플링 및 로그 확률 필드를 제거합니다.^[2]
돌이킬 수 있는 모델 스위치 뒤에 배포한 다음 자신의 fixtures에서 정확성, 부작용, 지연, 토큰 및 비용을 비교합니다.

1단계: 프로덕션 키가 모델을 볼 수 있는지 증명하기

요청을 편집하기 전에 모델 발견을 사용하세요. 공식 ID는 gpt-6-astra이지만 접근 권한은 여전히 API 계정 및 키에 연결되어 있습니다. 문서에 표시된 모델은 롤아웃 중에 모든 자격증명에 같은 시간에 반환되지 않을 수 있습니다.^[1]

환경 변수에서 키를 유지하고 로컬에서 응답을 필터링합니다:

test -n "$OPENAI_API_KEY" || {
  echo "OPENAI_API_KEY is not set" >&2
  exit 1
}

curl --fail-with-body --silent \
  https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  | jq -e '.data[] | select(.id == "gpt-6-astra") | .id'

set -x를 추가하지 마세요. 환경을 인쇄하지 마세요. 명령에 실제 키를 붙여넣지 마세요. 프런트엔드 코드에 넣지 마세요. CI 작업은 자격 증명 저장소에서 주입한 비밀로 동일한 검사를 실행할 수 있습니다.

발견을 게이트로 취급합니다:

결과	의미	마이그레이션 조치
정확한 ID 반환	키가 `gpt-6-astra`를 발견할 수 있습니다	단일 요청 스모크 테스트로 계속 진행
HTTP 401 또는 403	인증 또는 권한 문제	자격증명 또는 프로젝트 수정; 애플리케이션 트래픽 변경 금지
유효한 응답, ID 없음	모델이 현재 해당 키에 대해 검색 불가능	이전 모델 유지 및 나중에 다시 확인
네트워크 또는 5xx 오류	가용성을 알 수 없음	제한된 백오프로 읽기 재시도; 부재로 취급 금지

발견은 필수이지만 전체 준비 테스트는 아닙니다. 할당량, 요청 형태, 지역 설정 또는 도구 정책이 여전히 나중 호출을 거부할 수 있습니다. 발견 시간과 키 식별자를 저장합니다. 키 값은 저장하지 마세요.

모델이 문서에 나타나지만 애플리케이션이 여전히 호출할 수 없으면 라이브 카탈로그가 유용한 증거입니다. 자격증명과 환경을 확인합니다. 발표나 스크린샷에서 액세스를 추론하지 마세요.

2단계: 현재 요청 인벤토리 작성하기

엔드포인트를 변경하기 전에 현재 동작을 캡처합니다. 각 프로덕션 요청 클래스에 대해 다음을 기록합니다:

현재 모델 및 엔드포인트;
시스템 또는 개발자 지침 및 프롬프트 버전;
입력 유형 및 일반적인 컨텍스트 크기;
도구, 도구 스키마, 승인 규칙 및 허용된 부작용;
샘플링, 추론, 출력, 캐시 및 서비스 계층 매개변수;
성공 기준, 지연 시간 제한 및 폴백 동작;
파서가 응답에서 읽는 필드;
토큰 및 비용 조정에 사용되는 로그.

이 인벤토리는 종종 혼합되는 세 가지 마이그레이션을 분리합니다:

모델을 gpt-6-astra로 변경;
Chat Completions에서 Responses로 이동;
새로운 기능을 활용하기 위해 프롬프트 또는 도구 동작 변경.

가장 작은 호환 프롬프트 변경으로 처음 두 가지를 배포합니다. 프롬프트 재설계는 전송 및 파서가 통과한 후에 따를 수 있습니다. 세 가지가 모두 함께 이동하면 실패한 canary는 모델, 엔드포인트, 프롬프트 또는 도구 루프 중 어느 것이 회귀를 일으켰는지 알려주지 않습니다.

3단계: 일반 Responses API 요청 수립하기

도구, 스트리밍 또는 긴 컨텍스트 없이 시작하세요. 첫 요청은 인증, 모델 선택, 응답 구문 분석 및 사용 로깅을 증명해야 합니다.

import OpenAI from 'openai';

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) throw new Error('Set OPENAI_API_KEY in your secret store');

const client = new OpenAI({ apiKey });

const response = await client.responses.create({
  model: 'gpt-6-astra',
  reasoning: { effort: 'low' },
  input: [
    {
      role: 'user',
      content: [
        {
          type: 'input_text',
          text: 'Return a three-item rollback checklist for a database index change.',
        },
      ],
    },
  ],
});

console.log(response.output_text);
console.log(response.usage);

OpenAI의 모델 페이지는 Responses 및 Chat Completions를 지원되는 엔드포인트로 나열합니다. 마이그레이션 가이드는 Astra에 Responses를 권장하며 도구가 관련될 때 특히 필요합니다.^[1]^[2] 초기 프롬프트를 눈으로 검토할 수 있을 정도로 결정론적으로 유지하되 자신의 키가 완료될 때까지 성공적인 실행을 주장하지 마세요.

reAPI를 통해 Astra를 호출하면 경로별 GPT-6 Astra 문서를 사용합니다. 현재 계약은 OpenAI 호환 Chat Completions이며 자체 지원 매개변수 집합을 노출합니다. 문서가 다른 엔드포인트를 지칭하는 경로에 위의 직접 OpenAI Responses 본문을 보내지 마세요.

4단계: 에스컬레이션 규칙이 있는 추론 수준 선택하기

OpenAI는 GPT-6 Astra에 low, medium, high, xhigh 및 max를 문서화합니다. 또한 none은 지원되지 않음을 명시합니다. 마이그레이션 가이드는 기존 none 또는 minimal 설정이 low로 이동해야 한다고 명시합니다. 그렇지 않으면 애플리케이션의 유효한 추론 수준을 유지하여 시작합니다.^[1]^[2]

수준	여기서 시작	다음의 경우에만 승격
`low`	분류, 추출, 간단한 계획 또는 첫 번째 전송 스모크 테스트	정의된 정확성 또는 도구 사용 게이트가 실패함
`medium`	작업에 더 많은 계획이나 판단이 필요하고 low가 알려진 요구 사항을 놓침	같은 fixture가 프롬프트 결함 제거 후에도 여전히 실패함
`high`	복잡한 디버깅, 검토 또는 실패가 높은 수정 비용을 가지는 결정	작은 대표 세트가 더 많은 노력에서 측정 가능한 이득을 보여줌
`xhigh`	긴 어려운 작업으로 추가 지연 및 토큰을 정당화할 수 있는 값	평가가 높을 때 목표 수락 메트릭에서 이김을 보여줌
`max`	모든 낮은 수준을 측정한 후 가장 어려운 제한된 경우	측정되지 않은 전역 기본값으로 절대 금지

이 "여기서 시작" 항목은 공급업체 성능 주장이 아닌 배포 조언입니다. 애플리케이션이 임계값을 결정합니다. 유용한 정책은 프롬프트가 얼마나 많은 사고를 필요로 하는지 추측하지 않고도 작성할 수 있습니다:

low에서 실행
기계 확인 가능한 수락 게이트가 전송 오류 없이 실패하면:
    한 번 medium으로 재시도
작업이 명시적으로 높은 가치이고 medium이 실패하면:
    인간 검토 또는 별도로 승인된 높은 수준의 큐로 라우팅

도구 작업이 외부 상태를 변경할 수 있은 후 높은 수준의 노력으로 재시도하는 것을 피하세요. 먼저 작업을 조정합니다. 노력 에스컬레이션은 읽기 전용 분석에는 안전합니다. "전송", "구매", "삭제" 또는 "배포"에는 자동으로 안전하지 않습니다.

5단계: 의도적으로 도구 호출을 Responses로 이동하기

OpenAI는 GPT-6 Astra 도구 호출이 Responses API를 필요로 한다고 명시합니다. Chat Completions는 모델에 대해 나열된 상태로 유지되지만 도구가 있는 Chat Completions 요청은 OpenAI가 문서화하는 마이그레이션 경로가 아닙니다.^[2]

Responses 요청의 함수 정의는 다음과 같이 보일 수 있습니다:

const tools = [
  {
    type: 'function',
    name: 'read_change_ticket',
    description: 'Read one change ticket by its approved identifier.',
    parameters: {
      type: 'object',
      properties: {
        ticket_id: { type: 'string' },
      },
      required: ['ticket_id'],
      additionalProperties: false,
    },
    strict: true,
  },
];

const response = await client.responses.create({
  model: 'gpt-6-astra',
  reasoning: { effort: 'medium' },
  input: 'Read change ticket CHG-1042 and list its stated rollback steps.',
  tools,
});

모델은 함수를 요청할 수 있습니다. 애플리케이션은 여전히 인수를 검증하고 허용된 작업을 실행하고 도구 결과를 계속에서 반환합니다. 원래 호출 ID를 유지합니다. 모델 이름 변경이 인증, 확인 또는 멱등성 제어를 우회하도록 허용하지 마세요.

다음을 위해 별도의 fixtures를 빌드합니다:

올바른 도구 선택 (메모리에서 답변하기보다);
스키마를 통과하는 인수 생성;
제공된 ticket ID가 없을 때 하나를 발명하는 것을 거부;
도구 오류 처리 (부작용 반복 없음);
소스 구분을 떨어뜨리지 않고 여러 읽기 결과 결합;
돌이킬 수 없는 작업 전에 승인을 위해 일시 중지.

OpenAI는 또한 Astra에 대해 비동기 도구 호출 및 중간 턴 스티어링을 문서화합니다. 동기 루프가 올바를 후에 채택합니다. 자신의 타임아웃, 취소 및 계속 테스트가 필요한 상태를 추가합니다.^[2]

6단계: canary 전에 호환되지 않는 매개변수 제거하기

프로덕션 트래픽에서 오래된 요청 옵션을 발견할 때까지 기다리지 마세요. OpenAI의 마이그레이션 가이드는 제거할 필드를 나열합니다.^[2]

기존 필드 또는 값	GPT-6 Astra 마이그레이션
`temperature`	제거
`top_p`	제거
`top_logprobs`	제거
Chat Completions `logprobs`	제거
Responses `include: ["message.output_text.logprobs"]`	해당 항목 제거
추론 `none` 또는 `minimal`	`low`로 시작
Responses `reasoning_effort`	중첩된 `reasoning: { effort: "..." }`로 이름 변경
도구가 있는 Chat Completions	도구 사용 경로를 Responses로 이동
이전 GPT-5.6 `prompt_cache_retention`	`prompt_cache_options.ttl: "30m"`으로 마이그레이션 검토

마지막 캐시 변경은 GPT-5.5 또는 이전에서 마이그레이션할 때 적용됩니다. Astra가 대상이기 때문에 필요하지는 않습니다. 서비스 계층 호환성도 데이터 거주지에 따라 달라집니다. OpenAI는 GPT-6 Astra Fast 및 Priority가 EU 데이터 거주지에서 사용 불가능하다고 명시하므로 공식 호환성 지침이 변경되지 않으면 거기서 Standard 처리를 유지합니다.^[2]

요청 빌더, 공유 SDK 래퍼, 기본값 및 관찰 가능성 미들웨어를 검색합니다. 제거된 필드는 호출 사이트에서 멀리 주입될 수 있습니다. canary 중에 최종 요청 키의 새니타이즈된 표현을 기록합니다. 절대 헤더, 비밀, 전체 개인 데이터 또는 기밀 프롬프트 본문은 로깅하지 마세요.

7단계: 트래픽 전송 전에 수락 정의하기

애플리케이션 결과가 통과할 때 마이그레이션이 통과합니다. HTTP 200을 반환하지 않습니다. 프로덕션 형태의 작업에서 그려진 fixtures를 사용하고 이전 및 새 경로에서 동일한 입력을 점수합니다.

게이트	기록할 항목	통과 규칙 예시
정확성	필수 사실 또는 주장	모든 필수 통과 주장이 성공
형식	스키마 구문 분석 및 필수 키	수복 통과 필요 없음
도구 사용	도구 선택 및 인수 검증	허가되지 않거나 발명된 호출 없음
부작용	멱등성 및 승인 동작	필수 승인 전 조치 없음
완료	작업이 수락된 결과에 도달	버려지거나 루프되는 실행 없음
지연 시간	종단 간 및 첫 번째 유용한 출력	경로의 제품 마감 내
사용	입력, 캐시된 입력, 추론/출력, 도구 호출	모든 시도마다 저장됨
비용	정산된 API 비용	작업별 예산 내

유용한 비용 방정식은 거부된 작업을 포함합니다:

수락된 작업당 비용 = 총 정산된 API 비용 / 수락된 작업

같은 고정 fixtures에서 이전 경로와 Astra를 실행합니다. 도구 데이터, 권한, 타임아웃 및 평가자를 동일하게 유지합니다. Astra 프롬프트가 변경되어야 하면 버전을 지정하고 비교를 모델 전용 결과가 아니라 모델 플러스 프롬프트 마이그레이션으로 보고합니다.

OpenAI는 광범위한 출시 평가를 게시하지만 연구 또는 API 하네스가 프로덕션 ChatGPT 동작과 다를 수 있음을 명시합니다.^[3] 수락 세트는 좁은 질문에 답변합니다. 이 애플리케이션이 계약을 깨지 않고 개선되나요?

8단계: canary, 관찰 및 롤백을 한 스위치 떨어지게 유지하기

새 경로를 다음과 같은 설정 뒤에 배포합니다:

PRIMARY_MODEL=current-production-model-id
ASTRA_CANARY_MODEL=gpt-6-astra
ASTRA_CANARY_PERCENT=1

이름은 예시입니다. 키에 실제로 반환되는 식별자를 사용하세요. 오프라인 게이트가 통과한 후에만 내부 트래픽 또는 재생된 읽기 전용 fixtures로 시작합니다. 그런 다음 작은 라이브 백분율을 노출합니다.

롤백을 설명할 수 있을 정도의 데이터를 저장합니다:

경로 및 정확한 모델 ID;
프롬프트 및 도구 스키마 버전;
추론 수준;
요청 ID 및 타임스탐프;
새니타이즈된 오류 클래스;
입력, 출력 및 캐시된 토큰 사용;
도구 호출 및 승인;
수락 결정 및 거부 이유.

롤백 조건은 canary 전에 작성해야 합니다. 예시로는 필수 통과 정확성 회귀, 스키마 실패, 허가되지 않은 도구 시도, 예산 위반, 지속된 지연 위반 또는 모델이 발견에서 사라짐이 포함됩니다. 하나가 트리거되면 주 모델을 이전 경로로 설정하고 새로운 Astra 작업을 중지하고 이미 시작된 부작용 작업이 조정되도록 하세요. 무조건 재제출하지 마세요.

첫 출시 중에 이전 요청 빌더를 삭제하지 마세요. 새 경로가 계획된 관찰 기간을 통과하고 롤백 결정이 검토된 후에만 제거합니다.