프롬프트

워크스페이스와 API 키를 갖추었다면(소개 참조), 다음 단계는 프롬프트입니다. 이 페이지는 OrcaRouter 프롬프트 레지스트리의 정식 레퍼런스입니다 — 무엇인지, 어떻게 사용하는지, 그리고 게이트웨이의 나머지 부분과 어떻게 결합하는지.

1. 프롬프트 레지스트리란

프롬프트 레지스트리는 워크스페이스 범위의 재사용 가능한 시스템 메시지 라이브러리입니다. 프롬프트를 한 번 저장하고 임의의 API 키를 그것에 바인딩하거나(또는 요청별로 prompt_ref를 전송), 게이트웨이는 업스트림 모델로 요청을 전달하기 전에 그 프롬프트를 시스템 메시지로 주입합니다. 프롬프트를 편집하면 그것에 바인딩된 모든 키가 바로 다음 호출에서 업데이트됩니다. 재배포 없음. 코드 변경 없음. SDK 업그레이드 없음. 바인딩은 애플리케이션이 아니라 게이트웨이에 존재합니다. 이는 Langfuse와 LangSmith가 개척한 것과 동일한 아이디어이지만 한 가지 차이가 있습니다: OrcaRouter는 전달 계층입니다. 앱 코드는 이전과 정확히 동일하게 /v1/chat/completions를 호출합니다. 게이트웨이가 프롬프트를 해석하고 주입합니다. 애플리케이션에 설치할 것이 없습니다. 프롬프트는 워크스페이스 범위입니다 — 모든 멤버가 워크스페이스의 프롬프트를 보며 테넌트 경계를 넘지 않습니다.

2. 빠른 시작 — 5단계로 첫 프롬프트 바인딩하기

프롬프트 생성

콘솔에서 /console/prompts로 이동하여 New prompt를 클릭합니다. 이름을 support-agent로 지정합니다. 시스템 메시지를 붙여넣습니다:

“당신은 Acme의 간결한 지원 에이전트입니다. 2문장 이내로 답하세요.”

저장 — 이로써 버전 1이 생성됩니다.

키 바인딩

/console/token으로 이동하여 API 키를 생성 또는 편집하고, Prompt 드롭다운에서 support-agent를, Label 드롭다운에서 production을 선택합니다.

요청 전송

그 키를 사용하여 이전과 정확히 동일하게 OrcaRouter를 호출합니다:

curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "What are your business hours?"}
    ]
  }'

게이트웨이는 전달 전에 저장된 시스템 메시지를 앞에 추가합니다. 응답 헤더 X-Orca-Prompt: support-agent@production:v1이 주입된 프롬프트를 확인해 줍니다.

프롬프트 편집

/console/prompts로 돌아가 support-agent를 편집 — 시스템 메시지를 변경합니다. 저장 — 버전 2가 자동으로 생성됩니다; production은 여전히 v1을 가리킵니다.

프로모트

프롬프트 행에서 Labels를 클릭하고, production을 v2로 옮기고 확인합니다. 당신의 키를 통한 바로 다음 요청은 v2의 시스템 메시지를 받습니다. 애플리케이션 변경 없음.

이것이 핵심 가치입니다.

3. 개념: 프롬프트, 버전, 라벨

개념	정의	가변성
프롬프트	이름이 지정된, 워크스페이스 범위 항목. 식별자: `name`(정규식 `^[a-zA-Z0-9._-]{1,128}$`).	소프트 삭제 가능(30일 휴지통 + 퍼지).
버전	프롬프트 내용의 불변 스냅샷. 매 저장 시 자동 생성. 식별자: 단조 증가 `int`.	불변 — 절대 편집되지 않으며 재사용되지 않음.
라벨	버전을 가리키는 이동 가능 포인터(예: `production` → v7).	프로모트를 통해 원자적으로 이동; 감사 로그가 모든 이동을 기록.

예약된 라벨

production은 모든 신규 프롬프트의 첫 버전에서 자동으로 v1에 고정 됩니다. 이를 옮기는 것은 프로덕션 트래픽 스위치입니다 — Owner 전용 RBAC.
latest는 게이트웨이가 자동 유지하며 항상 최신 버전을 가리킵니다. latest는 수동으로 옮길 수 없습니다.

나중에 Labels 다이얼로그를 통해 커스텀 라벨(예: staging, canary, eu-prod)을 추가하고 키를 그것에 바인딩할 수 있습니다. 라벨이 버전에 고정되기 전까지는 name@<그-라벨>에 바인딩된 키가 주입 없이 페일 오픈됩니다.

왜 이런 모양인가

불변 버전과 이동 가능 라벨의 분리는 코드 변경 없이 배포하는 프리미티브입니다. 애플리케이션 코드는 라벨을 참조합니다(키 바인딩을 통한 암묵적, 또는 prompt_ref를 통한 명시적). 프로모트는 라벨을 이동시킵니다 — 애플리케이션은 어떤 코드 변경도 없이 다음 호출에서 새 내용을 봅니다. 롤백은 그저 더 오래된 버전을 라벨에 프로모트하는 것일 뿐입니다.

4. 프로덕션 패턴: 프로모트, 롤백, 단계적 릴리스

프로모트

프롬프트 행에서 Labels를 열고 대상 버전을 선택한 후 Promote를 클릭합니다. 라벨 이동은 원자적이고 감사됩니다(감사 로그는 누가 어느 라벨을 어느 버전에서 어느 버전으로, 언제 옮겼는지 보여줍니다). name@<label>에 바인딩된 모든 키는 다음 요청에서 새 버전을 가져옵니다.

Owner 전용. 프로모트는 프로덕션 트래픽 변경이며 워크스페이스 Owner에게 게이팅됩니다(POST /api/prompt/:id/label). Developer와 Viewer는 라벨 목록과 감사 기록을 볼 수 있지만 Promote 버튼은 보이지 않습니다; 다이얼로그는 “Owner에게 문의” 인라인 힌트를 표시하여 게이트가 침묵하기보다 가시화되도록 합니다.

롤백

History 드로어에서 더 오래된 버전에 대해 Restore. Restore는 그 버전의 내용을 새 버전으로 전진 복사하고(히스토리는 절대 변경되지 않음) latest를 그것으로 옮깁니다. 트래픽이 실제로 폴백하게 하려면 관련 라벨을 복원된 버전으로 Promote하세요.

단계적 릴리스

카나리아 키는 name@staging에, 프로덕션 키는 name@production에 바인딩하세요. staging을 새 버전으로 프로모트하고, Insights에서 관찰한 뒤, 만족스러우면 production을 프로모트하세요. 키 편집 없음, 배포 없음, SDK 업데이트 없음.

A/B 트래픽 분할

Label 다이얼로그에는 Split traffic 토글이 있습니다. 이를 활성화하여 단일 라벨이 가중치 분배로 여러 버전을 가리키게 할 수 있습니다(예: v7: 60%, v8: 40%). 버킷팅은 (workspace, token, request-id)별로 결정적이므로 단일 대화는 재시도 전반에서 동일한 버킷에 머무릅니다.

5. 템플릿: `{{var}}` 치환

프롬프트 내용은 Mustache 스타일의 {{var}} 플레이스홀더를 지원합니다. 호출자 값은 prompt_ref.variables에서 옵니다(§6 참조). 규칙:

단일 패스 치환. 변수 값은 리터럴 텍스트로 방출됩니다. 템플릿으로 재평가되지 NOT — 이는 호출자가 제공한 값이 추가 {{...}} 지시문을 주입하려는 프롬프트 인젝션을 방지합니다.
알 수 없는 플레이스홀더는 그대로 유지. 플레이스홀더 {{foo}}에 일치하는 변수가 없으면 리터럴 {{foo}}가 방출됩니다(그리고 경고가 기록됩니다). 변수 누락으로 요청이 실패하는 일은 결코 없습니다.
점 접근. 호출자가 중첩 맵을 전달하면 {{user.name}}은 중첩 객체를 순회합니다.
섹션. {{#flag}}...{{/flag}}는 flag가 참일 때만 블록을 표시합니다. 반전 섹션({{^flag}}...)은 flag가 누락/거짓일 때 블록을 표시합니다.
렌더링된 크기 상한: 256 KiB. 최종 렌더링된 텍스트가 이 임계값을 초과하면 주입 전체가 건너뛰어지고(응답에 X-Orca-Prompt 헤더가 포함되지 않음) 요청은 변경 없이 전달됩니다 — 변수 폭증 증폭에 대한 보호입니다.

외부 프로바이더는 그들의 네이티브 구문을 존중합니다:

Langfuse 프롬프트는 동일한 {{var}} Mustache 구문을 사용합니다.
LangSmith 프롬프트는 매니페스트에서 template_format: f-string | mustache 를 선언합니다. 게이트웨이는 그 선언을 존중합니다.

6. 요청별 오버라이드: `prompt_ref`

키 바인딩을 변경하지 않고 요청별로 프롬프트를 오버라이드 또는 선택합니다. 요청 본문에 최상위 prompt_ref 필드를 추가합니다:

{
  "model": "openai/gpt-4o-mini",
  "messages": [
    {"role": "user", "content": "Who is on call tonight?"}
  ],
  "prompt_ref": {
    "name": "support-agent",
    "label": "staging",
    "variables": {
      "product_name": "Orca"
    }
  }
}

우선순위(최고가 승리): 요청 prompt_ref > 키 바인딩(네이티브 PromptId/PromptLabel 또는 PromptProviderId) > 채널 SystemPrompt

없음.

prompt_ref는 게이트웨이가 소비하며 업스트림으로 전달되기 전에 제거됩니다 — 엄격한 프로바이더는 알 수 없는 필드를 결코 보지 못합니다. 형태:

type PromptRef = {
  provider?: string;   // omit for native; or the provider's configured name for external
  name: string;        // required
  label?: string;      // mutually exclusive with `version`
  version?: string;    // pin to a specific version
  variables?: { [key: string]: string };  // mustache substitution
};

사용 사례: 동일한 키에 대한 서로 다른 프롬프트 버전의 A/B 테스트; 호출자 측에서의 카나리아 롤아웃; 요청별 변수 보간.

7. 채팅 형태 프롬프트(시스템 + few-shot)

대부분의 프롬프트는 단일 시스템 문자열입니다. 하지만 때로는 게이트웨이가 더 풍부한 템플릿 — 시스템 메시지에 user/assistant 턴의 few-shot 시퀀스를 더한 것 — 을 주입하기를 원할 수 있습니다. 레지스트리는 이를 kind: 'chat' 으로 지원합니다. 콘솔의 Create prompt 모달은 Text / Chat 토글을 노출합니다. Chat을 선택하면 콘텐츠 에디터가 {role, content} 행의 목록(system, user, assistant)으로 바뀝니다 — 필요한 만큼 추가합니다. 저장 시 행들은 messages_json으로 영속화됩니다. 일단 생성되면 kind는 불변입니다. 주입 시 동작:

요청에 시스템 메시지 없음 ⇒ 게이트웨이가 템플릿의 시스템 메시지를 앞에 추가하고, 템플릿의 few-shot 턴은 호출자 메시지 앞에 나타납니다.
요청에 시스템 메시지 있음 ⇒ 주입은 포맷 어댑터의 기본값을 따릅니다. OpenAI 형식 요청의 경우 템플릿의 시스템 메시지가 앞에 추가되고, Claude 형식 요청의 경우 템플릿의 시스템이 네이티브 system 매개변수에 들어갑니다.

외부 채팅 프롬프트(Langfuse, LangSmith)의 경우, 게이트웨이는 템플릿을 동일한 모양으로 평탄화합니다.

8. 게이트웨이 나머지 부분과의 관계

표면	프롬프트와 어떻게 결합되는가?
Models	프롬프트는 모델 비종속적입니다. 동일한 프롬프트가 GPT-5, Claude, Gemini 위에서 동작합니다. 라우팅은 요청의 `model`과 키의 그룹에 따라 업스트림 모델을 선택합니다 — 프롬프트는 이를 오버라이드하지 않습니다.
Routing	라우팅이 먼저 실행되고, 프롬프트 리졸버는 그 후에 실행됩니다. 따라서 해석된 프롬프트는 라우터가 선택한 어떤 채널 위에든 — 폴백 체인을 가로질러서도 — 탑니다.
Guardrails	Guardrails는 콘텐츠를 검사하고 마스킹하는 독립된 게이트입니다. 프롬프트는 시스템 메시지를 주입합니다; 정책을 우회하지 않습니다. 요청은 둘 다 가질 수 있습니다 — guardrails는 항상 실행됩니다.
API Keys	키는 라벨에서 프롬프트에 바인딩됩니다(예: `support-agent@production`). 바인딩은 게이트웨이의 키에 존재하므로, 새 버전을 프로모트하면 그 라벨의 모든 키가 한 번에 이동합니다.
Insights	모든 요청은 로그 행에 `prompt_id`, `prompt_version`, `prompt_label`을 스탬프합니다. Insights는 프롬프트별로 슬라이스합니다 — 사용량, 오류율, 지연 시간, 비용.

라우터는 유일한 모델 권한자로 남습니다. config를 선언하는 외부 프롬프트(Langfuse config.model, LangSmith model_config)일지라도 — 게이트웨이는 그 필드들을 무시합니다. 프롬프트는 텍스트만 주입합니다; 모델 선택은 라우터의 일입니다.

9. 외부 소스: Langfuse, LangSmith, Generic HTTP

페더레이션: 외부 프롬프트 소스를 한 번 연결한 후, 그곳에 호스팅된 이름들에 대해 키를 바인딩하거나 prompt_ref를 전송합니다. 네이티브와 외부 프롬프트는 동일하게 바인딩되고 제공됩니다 — 리졸버 백엔드만 다를 뿐입니다. 지원되는 소스:

Langfuse — GET {base}/api/public/v2/prompts/{name}?label=..., public:secret 쌍의 Basic 인증. 텍스트와 채팅 프롬프트.
LangSmith — GET {base}/commits/{owner}/{name}/{tag|hash|latest}, x-api-key 헤더. 게이트웨이는 직렬화된 매니페스트를 파싱하여 messages/text와 template_format 선언을 추출합니다. 임베딩된 model_config / model_provider 필드는 제거됩니다(심층 방어: 레지스트리는 텍스트만 제공).
Generic HTTP — 페치당 단일 HTTP 호출을 노출하는 임의의 프롬프트 레지스트리를 위한 운영자 구성 커넥터. 구성 가능한 필드는 아래 참조.

소스는 Integrations → Prompt sources에서 연결합니다(Owner 전용 구성; 시크릿은 암호화 저장되며 읽기 시 마스킹됩니다). Test & Save 플로우는 영속화 전에 알려진 프롬프트를 드라이 해석하고 SSRF 차단된 URL(루프백, 사설, 링크-로컬, 메타데이터 범위)을 거부합니다.

Generic HTTP 커넥터 필드

Generic HTTP 소스는 “하나의 HTTP 호출과 하나의 응답 모양을 기술하는” 어댑터입니다. 셀프 호스팅 프롬프트 저장소와 자체 백엔드 통합이 필요 없는 서드파티 플랫폼(PromptLayer, 간단한 커스텀 API 등) 모두에 사용됩니다. 필드는 의도적으로 작게 유지됩니다 — 다단계 플로우나 프로바이더 고유 프로토콜은 범위 밖입니다.

필드	기본값	역할
URL template	필수	`{name}` / `{label}` / `{version}` 플레이스홀더가 있는 완전한 요청 URL. 경로의 플레이스홀더는 `PathEscape`를, 쿼리 문자열의 플레이스홀더는 `QueryEscape`를 사용하여 프롬프트 이름의 `&`/`=`가 추가 쿼리 매개변수를 주입할 수 없게 합니다.
HTTP method	`GET`	`GET` 또는 `POST`. 플랫폼이 요청 본문을 요구할 때 POST를 선택합니다.
Auth header name	`Authorization`	시크릿이 전송되는 HTTP 헤더. 커스텀 헤더를 사용하는 프로바이더의 경우 `X-API-KEY`(또는 유사)로 설정합니다.
Auth scheme prefix	`Bearer` (말미 공백 포함)	헤더 값에서 시크릿 앞에 붙는 문자열. 플랫폼이 원시 API 키를 기대하면 빈 값으로, 또는 `Token` / 기타 커스텀 접두사로 설정합니다.
Body template	빈 값	POST 전용. 두 가지 플레이스홀더 계열을 가진 원시 요청 본문. 그대로: `{name}` / `{label}` / `{version}`은 리터럴 값으로 치환됩니다(form-encoded, XML 또는 템플릿 본문에 사용 — 이스케이핑은 본인 책임). JSON-safe: `{name_json}` / `{label_json}` / `{version_json}`은 완전히 인용된 JSON 문자열 리터럴(예 `"hello"`)로 치환됩니다 — JSON 본문 안에서 이것들을 사용하여 `"` / `\` / 제어 문자를 포함한 요청 측 프롬프트 이름이 업스트림에 형제 필드를 주입할 수 없게 합니다.
Response JSON path	빈 값	프롬프트 페이로드가 위치한 응답 JSON으로의 선택적 점 경로(예 `data.0.template.messages`). 빈 값 = 최상위 `text` / `prompt` / `messages` 모양을 자동 감지.

예 — PromptLayer 수동 연결:

URL template:        https://api.promptlayer.com/rest/get-prompt-template?prompt_name={name}&label={label}&version={version}
HTTP method:         GET
Auth header name:    X-API-KEY
Auth scheme prefix:  (empty)
Body template:       (empty)
Response JSON path:  prompt_template.messages
Secret:              <your PromptLayer API key>

복원력

TTL 캐시(기본 60초)로 프롬프트 편집이 1분 이내에 전파됩니다.
Stale-while-revalidate — 다음 새로고침이 백그라운드에서 실행되는 동안 캐시 값이 제공됩니다.
Stale-on-error — 외부 소스가 5xx를 반환하거나 타임아웃되면, 게이트웨이는 마지막으로 알려진 정상 응답을 제공합니다. 사용자 트래픽이 프로바이더 장애로 인해 강하게 실패하는 일은 결코 없습니다.

10. 관측성

프롬프트가 주입된 모든 요청은 네 개의 빵 부스러기를 남깁니다.

응답 헤더

X-Orca-Prompt: support-agent@production:v7 (native)

형식:

네이티브: name@label:vN (native)(버전 int를 알 수 없을 때는 name@label (native)).
외부: name@label:<provider-version-tag> (langfuse) 등.
라벨 생략 ⇒ @label 세그먼트 없음.

로그 칼럼

Log.PromptId, Log.PromptVersion, Log.PromptLabel — 타입 지정된 칼럼, Insights 쿼리를 위해 인덱싱됨.

Insights 드릴다운

/console/insights에서 필터 행에 Prompt 패싯이 있습니다 — 프롬프트를 선택하면 모든 탭(지연 시간, 오류, 비용)이 그 prompt_id로 필터됩니다. 이것이 “프롬프트를 편집했다 — 트래픽에서 무엇이 바뀌었는가?” 의 루프 클로저입니다.

감사

모든 라벨 이동과 롤백은 프롬프트의 Promote history에 액터 사용자 id, 타임스탬프, from-version, to-version과 함께 기록됩니다. 모든 멤버에게 가시; 변경은 Owner 역할에 게이팅.

11. API 레퍼런스

모든 라우트는 X-Workspace-Id 헤더를 통해 워크스페이스 범위입니다. RBAC는 일관되게 강제됩니다: 읽기는 모든 멤버에게 개방; 쓰기는 Developer+; 프로덕션 트래픽 변경(라벨 이동, 롤백, 프로바이더 구성, webhook)은 Owner 전용.

메서드 및 경로	역할	목적
`GET /api/prompt/`	Member	프롬프트 목록(페이지네이션, `?tag=` 지원).
`GET /api/prompt/?in_trash=true`	Owner	소프트 삭제된 프롬프트 목록(Owner 전용 — 복구 클래스).
`GET /api/prompt/search`	Member	키워드 + 태그 검색(레이트 제한 있음).
`GET /api/prompt/tags`	Member	워크스페이스 태그 typeahead.
`GET /api/prompt/:id`	Member	단일 프롬프트 상세.
`GET /api/prompt/:id/versions`	Member	버전 기록(최신순).
`GET /api/prompt/:id/labels`	Member	현재 라벨 → 버전 맵.
`GET /api/prompt/:id/tags`	Member	단일 프롬프트의 태그 집합.
`GET /api/prompt/:id/label_history`	Member	프로모션 감사 로그.
`GET /api/prompt/:id/analytics`	Member	프롬프트별 사용량 차트 데이터.
`GET /api/prompt/analytics/top`	Member	워크스페이스 전반에서 가장 많이 사용된 프롬프트.
`POST /api/prompt/`	Developer+	프롬프트 생성(text 또는 chat).
`PUT /api/prompt/`	Developer+	프롬프트 업데이트(새 버전 생성).
`POST /api/prompt/:id/tags`	Developer+	태그 집합 교체.
`POST /api/prompt/:id/run`	Developer+	Playground “Try it”(레이트 제한 30/분/워크스페이스).
`DELETE /api/prompt/:id`	Developer+	휴지통으로 소프트 삭제(기본); `?purge=true`는 Owner 전용 하드 삭제.
`POST /api/prompt/:id/restore`	Owner	휴지통에서 복원.
`POST /api/prompt/:id/rollback`	Owner	더 오래된 버전을 새 버전으로 복원.
`POST /api/prompt/:id/label`	Owner	라벨을 버전으로 이동(원자적, 감사; A/B용 `split` 페이로드도 수용).

프롬프트 프로바이더(페더레이션)

메서드 및 경로	역할	목적
`GET /api/prompt_provider/`	Member	연결된 소스 목록(시크릿 마스킹).
`POST /api/prompt_provider/`	Owner	소스 연결.
`PUT /api/prompt_provider/`	Owner	소스 업데이트.
`DELETE /api/prompt_provider/:id`	Owner	연결 해제.
`POST /api/prompt_provider/test`	Owner	저장 전 드라이 해석.
`GET /api/prompt_provider/:id/prompts`	Member	외부 소스에서 사용 가능한 프롬프트 목록.
`POST /api/prompt_provider/:id/prompts/import`	Developer+	외부 프롬프트를 로컬 레지스트리로 가져오기.

프롬프트 webhook

메서드 및 경로	역할	목적
`GET /api/prompt_webhook/`	Member	webhook 목록.
`POST /api/prompt_webhook/`	Owner	webhook 추가(시크릿은 한 번만 반환).
`PUT /api/prompt_webhook/:id`	Owner	편집.
`DELETE /api/prompt_webhook/:id`	Owner	제거.
`POST /api/prompt_webhook/:id/test`	Owner	샘플 이벤트 전송.

Webhook 이벤트 전달

각 전달 시 설정한 URL로 JSON 봉투를 POST 합니다:

{
  "event": "label.promoted",
  "workspace_id": "ws_...",
  "occurred_at": "2025-01-15T08:30:00Z",
  "data": { "...": "event-specific fields" }
}

이벤트 종류: prompt.created, prompt.updated, prompt.deleted, label.promoted, version.rolled_back. 모든 전달에 포함되는 헤더:

X-Orca-Webhook-Id — 해당 webhook의 id (중복 제거에 사용).
X-Orca-Event — 봉투의 event 필드와 동일.
X-Orca-Signature — sha256=<hex> 형식이며, 여기서 <hex>는 원본 요청 본문에 대한 HMAC-SHA256(키는 webhook secret)입니다. 상수 시간 비교를 사용하세요.

요청 페이로드 추가

type ChatCompletionsRequest = {
  // ... all existing OpenAI-compatible fields ...
  prompt_ref?: PromptRef;  // gateway-only; stripped before upstream
};

12. FAQ

요청에서 프롬프트가 해석되지 않으면 어떻게 되나요?

동작은 기능을 한 번도 활성화하지 않은 워크스페이스와 바이트 단위로 동일합니다. 키가 바인딩되지 않았고, prompt_ref가 없으며, 채널 기본값도 설정되지 않았다면, 게이트웨이는 어떤 수정도 하지 않습니다. 응답은 X-Orca-Prompt 헤더를 가지지 않습니다. 로그 칼럼은 NULL입니다.이것이 회귀 보장입니다: 아무것도 바인딩되지 않았을 때 리졸버는 검증된 no-op입니다.

SystemPromptOverride는 레지스트리와 어떻게 상호작용하나요?

SystemPromptOverride는 기존의 채널 수준 시스템 프롬프트 기본값입니다. 바인딩된 레지스트리 프롬프트는 채널 기본값을 오버라이드합니다 — 문서화되어 있고 의도된 것입니다. 아무것도 해석되지 않을 때 채널 기본값은 이전과 정확히 동일하게 작동합니다.호출자의 요청이 이미 시스템 메시지를 포함하고 있을 때, 동작은 포맷 어댑터에 의해 결정됩니다: OpenAI 형식 요청은 템플릿의 시스템 메시지가 앞에 추가되고, Claude 형식 요청은 템플릿의 시스템을 네이티브 system 매개변수에 배치합니다.

특정 키가 사용할 수 있는 프롬프트를 제한할 수 있나요?

v1에서는 불가합니다. 어떤 키든 자신의 워크스페이스에 있는 어떤 프롬프트든 prompt_ref할 수 있습니다. 이는 Langfuse와 LangSmith의 워크스페이스 범위 키 모델과 일치합니다. 워크스페이스 간 액세스는 리졸버 수준에서 거부됩니다(릴레이 경로에서 재확인; 오래된 바인딩으로부터는 결코 신뢰되지 않음).키별 프롬프트 허용 목록은 가능한 향후 추가 사항입니다.

주입된 프롬프트 토큰은 청구되나요?

예. 주입된 시스템 프롬프트 토큰은 다른 시스템 메시지와 정확히 동일하게 사용량 / 쿼터 / 청구에 카운트됩니다. 모델의 컨텍스트 윈도우를 초과하는 과도하게 긴 프롬프트는 업스트림의 일반적인 오류를 반환합니다 — 게이트웨이는 사전 잘라내기를 하지 않습니다.

레지스트리가 모델을 오버라이드하나요?

아니요. 외부 프로바이더의 config.model / model_config 필드는 무시됩니다. 모델 선택은 라우터의 단독 권한으로 남아 있습니다 — 프롬프트는 텍스트만 주입합니다.

삭제된 프롬프트에 바인딩된 키는 어떻게 되나요?

리졸버는 누락된 / 삭제된 / 허가되지 않은 프롬프트를 페일-세이프 스킵으로 취급합니다 — 요청은 변경 없이 전달되며 호출자에게 오류가 발생하지 않습니다. Edit와 Promote 모달은 “N개의 키에서 사용됨” 배지를 표시하여 삭제나 프로모트 전에 폭발 반경을 볼 수 있게 합니다.

라벨 이동은 얼마나 빨리 전파되나요?

네이티브 라벨 이동은 거의 즉시입니다(게이트웨이는 초 단위의 제한된 간격으로 DB에서 동기화하며, 컨트롤러 쓰기 경로에서 로컬 맵 쓰기도 합니다). 외부 라벨 이동은 구성된 캐시 TTL 내에 나타납니다 (기본 60초). 둘 다 문서화된 기대치이며 결함이 아닙니다.

UI에서 채팅 프롬프트를 편집할 수 있나요?

예. Create prompt 모달은 Text / Chat 토글을 노출합니다; chat 모드는 구조화된 {role, content} 에디터를 보여줍니다. 일단 프롬프트가 생성되면 그 kind는 불변입니다(모양을 변경하려면 새 프롬프트를 생성합니다).

프롬프트 스탬프 빵 부스러기는 어디에 가나요?

사용자 대면 응답의 응답 헤더 X-Orca-Prompt.
요청 로그 행의 Log.PromptId / PromptVersion / PromptLabel 칼럼.
Insights Prompt 필터 패싯 — 프롬프트를 선택하면 모든 Insights 탭이 그 prompt_id로 필터됩니다.

webhook 시크릿을 어떻게 회전하나요?

PUT /api/prompt_webhook/:id를 통해 webhook을 편집하고 새로운 secret 값을 제공합니다. 새 시크릿은 응답에서 한 번 표시됩니다 — 그때 복사하세요; 이후 시크릿은 마스킹됩니다. (전용 회전 엔드포인트는 없습니다; 회전은 일반 편집입니다.)

​1. 프롬프트 레지스트리란

​2. 빠른 시작 — 5단계로 첫 프롬프트 바인딩하기

​3. 개념: 프롬프트, 버전, 라벨

​예약된 라벨

​왜 이런 모양인가

​4. 프로덕션 패턴: 프로모트, 롤백, 단계적 릴리스

​프로모트

​롤백

​단계적 릴리스

​A/B 트래픽 분할

​5. 템플릿: {{var}} 치환

​6. 요청별 오버라이드: prompt_ref

​7. 채팅 형태 프롬프트(시스템 + few-shot)

​8. 게이트웨이 나머지 부분과의 관계

​9. 외부 소스: Langfuse, LangSmith, Generic HTTP

​Generic HTTP 커넥터 필드

​복원력

​10. 관측성

​응답 헤더

​로그 칼럼

​Insights 드릴다운

​감사

​11. API 레퍼런스

​프롬프트

​프롬프트 프로바이더(페더레이션)

​프롬프트 webhook

​Webhook 이벤트 전달

​요청 페이로드 추가

​12. FAQ

1. 프롬프트 레지스트리란

2. 빠른 시작 — 5단계로 첫 프롬프트 바인딩하기

3. 개념: 프롬프트, 버전, 라벨

예약된 라벨

왜 이런 모양인가

4. 프로덕션 패턴: 프로모트, 롤백, 단계적 릴리스

프로모트

롤백

단계적 릴리스

A/B 트래픽 분할

5. 템플릿: `{{var}}` 치환

6. 요청별 오버라이드: `prompt_ref`

7. 채팅 형태 프롬프트(시스템 + few-shot)

8. 게이트웨이 나머지 부분과의 관계

9. 외부 소스: Langfuse, LangSmith, Generic HTTP

Generic HTTP 커넥터 필드

복원력

10. 관측성

응답 헤더

로그 칼럼

Insights 드릴다운

감사

11. API 레퍼런스

프롬프트

프롬프트 프로바이더(페더레이션)

프롬프트 webhook

Webhook 이벤트 전달

요청 페이로드 추가

12. FAQ