API로 Encrypted Vault 호출하기

TEE를 검증하고 데이터를 보내기 전에 엔드투엔드로 암호화하는 Cohere OHTTP 프록시를 통해 Encrypted Vault를 호출해요.

출처: 문서

본문

Encrypted Vault는 Standard Vault와 동일한 엔드포인트, 동일한 요청·응답 형태를 사용해요: 동일한 chat, embed, rerank 호출이에요. 유일하면서도 중요한 차이는 볼트 엔드포인트를 직접 호출할 수 없다는 점이에요. 트래픽은 반드시 Cohere OHTTP 프록시를 통과해야 해요. 이는 여러분의 환경에서 실행되는 클라이언트 측 기밀 컴퓨팅 구성 요소로, 데이터가 떠나기 전에 배포의 원격 증명을 검증하고 요청을 엔드투엔드로 암호화하며, 검증을 통과하지 못하면 연결을 거부해요.

Cohere OHTTP 프록시를 통한 두 가지 연결 방법

Cohere OHTTP 프록시는 두 가지 형태로 제공되며, 어떤 형태를 사용하느냐에 따라 사용할 수 있는 클라이언트가 결정돼요:

형태	무엇인가	사용할 수 있는 클라이언트
독립형 Cohere OHTTP 프록시	실행하는 독립형 로컬 프록시 컨테이너로, 증명을 검증하고 OHTTP를 투명하게 처리해요	Cohere SDK, raw HTTP, 또는 OpenAI 호환 (이 중 아무 것이나 로컬 프록시로 지정)
Cohere Python OHTTP 래퍼 (conseel)	httpx 기반 통신을 감싸서 증명을 검증하고 OHTTP를 처리하는 Python 패키지예요	Cohere SDK, OpenAI SDK, 기타 httpx 기반 Python SDK

어느 경우든 Cohere OHTTP 프록시는 여러분을 대신해 동일한 두 가지 작업을 해요:

증명 검증: 환경의 증명 토큰과 OHTTP 공개 키를 가져와서, 토큰이 실제로 Intel Trust Authority가 서명했는지 확인하고, 증명된 측정값이 승인된 정책과 일치하는지 확인하며, OHTTP 키가 그 증명된 환경에 바인딩되어 있는지 확인해요.
엔드투엔드 암호화: OHTTP를 사용해 증명된 환경으로 가는 모든 요청을 암호화하고 응답을 복호화해서, 로드 밸런서와 네트워크는 암호문(ciphertext)만 볼 수 있게 해요.

옵션 1: 어떤 클라이언트와 함께하는 Cohere OHTTP 프록시

Cohere OHTTP 프록시 컨테이너를 로컬에서 실행한 다음, 볼트 엔드포인트 대신 어떤 클라이언트든 로컬 프록시 주소로 지정해요. 프록시가 증명을 검증하고 증명된 환경으로 가는 모든 트래픽을 암호화하므로, 클라이언트 입장에서는 로컬 주소에 대한 평범한 평문 요청처럼 보여요. 즉 HTTP Cohere/OpenAI API 요청을 만드는 어떤 클라이언트든 변경 없이 동작해요.

Docker 같은 컨테이너 플랫폼으로 컨테이너를 실행해요:

BASH

docker run -it --rm \
  -p 127.0.0.1:8080:8080 \
  -e IN_HOST=0.0.0.0 -e IN_PORT=8080 \
  -e TARGET_URL=<YOUR_VAULT_ENDPOINT_URL> \
  ghcr.io/cohere-ai/tng-ingress:latest

latest 태그는 항상 현재 릴리스를 가리켜요. 프로덕션에서는 프록시 업데이트가 여러분이 선택할 때만 반영되도록 특정 버전(예: ghcr.io/cohere-ai/tng-ingress:0.6.0)을 고정해요.

그런 다음 프록시를 통해 Cohere SDK를 사용해요:

PYTHON

import cohere

# Point the SDK at the local Cohere OHTTP proxy instead of the vault endpoint.
co = cohere.ClientV2(
    api_key="<COHERE_API_KEY>",
    base_url="<LOCAL_OHTTP_PROXY_URL>",
)

response = co.chat(
    model="<YOUR_VAULT_MODEL_NAME>",
    messages=[
        {"role": "user", "content": "Hello to an encrypted vault!"}
    ],
)

print(response.message.content[0].text)

프록시를 통해 raw HTTP 요청을 만들어요:

cURL

curl "<LOCAL_OHTTP_PROXY_URL>/v2/chat" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<YOUR_VAULT_MODEL_NAME>",
    "messages": [{"role": "user", "content": "Hello to an encrypted vault!"}]
  }'

프록시를 통해 OpenAI 호환 클라이언트를 사용해요:

PYTHON

from openai import OpenAI

client = OpenAI(
    api_key="<COHERE_API_KEY>",
    base_url="<LOCAL_OHTTP_PROXY_URL>/v1",
)

response = client.chat.completions.create(
    model="<YOUR_VAULT_MODEL_NAME>",
    messages=[
        {"role": "user", "content": "Hello to an encrypted vault!"}
    ],
)

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

Note

Embed와 Rerank 호출도 Cohere OHTTP 프록시를 통해 동일하게 동작해요: 클라이언트나 프록시를 그대로 두고 볼트의 모델 이름으로 co.embed(...) 또는 co.rerank(...)(또는 해당 HTTP/OpenAI 호환 엔드포인트)를 호출하면 돼요.

옵션 2: Cohere Python OHTTP 래퍼

'conseel' 패키지를 사용해 httpx 기반 Python SDK의 전송 계층을, 증명을 검증하고 증명된 환경으로 가는 모든 트래픽을 암호화하는 것으로 교체해요. 클라이언트 생성 방식의 변경 외에는 SDK 사용법이 표준 볼트와 동일해요.

PyPI에서 패키지를 설치해요 (Linux/Mac에서 실행되는 x86/ARM 머신용):

pip install conseel

Cohere SDK와 함께 사용해요:

PYTHON

import cohere
import httpx
from conseel import Transport

co = cohere.ClientV2(
    api_key="<COHERE_API_KEY>",
    base_url="<YOUR_VAULT_ENDPOINT_URL>",
    httpx_client=httpx.Client(transport=Transport()),
)

response = co.chat(
    model="<YOUR_VAULT_MODEL_NAME>",
    messages=[
        {"role": "user", "content": "Hello to an encrypted vault!"}
    ],
)

print(response.message.content[0].text)

OpenAI SDK 같은 다른 httpx 기반 클라이언트와 함께 사용해요:

PYTHON

import openai
import httpx
from conseel import Transport

client = openai.OpenAI(
    api_key="<COHERE_API_KEY>",
    base_url="<YOUR_VAULT_ENDPOINT_URL>/v1",
    httpx_client=httpx.Client(transport=Transport()),
)

response = client.chat.completions.create(
    model="<YOUR_VAULT_MODEL_NAME>",
    messages=[
        {"role": "user", "content": "Hello to an encrypted vault!"}
    ],
)

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

보내기 전 검증

Cohere OHTTP 프록시는 엄격한 순서를 강제해요: 증명이 통과할 때까지 어떤 평문도 여러분의 환경을 떠나지 않아요. 각 세션에서 환경이 진짜 기밀 VM CPU와 NVIDIA GPU 하드웨어인지, 디버그 모드가 꺼져 있는지, 펌웨어와 코드 측정값이 승인된 정책과 일치하는지, 암호화 키가 그 환경에 속하는지 확인해요. 그래야만 요청을 암호화해서 보내요. 증명 토큰은 수명이 짧고 주기적으로 갱신되므로, 이 보장은 환경의 현재 상태를 반영해요.

검증은 설정 시점에만 국한되지 않아요: Cohere Python OHTTP 래퍼(conseel)를 사용하면 모든 추론 응답에 증명 인증서가 포함되고(x-tng-attestation-token 헤더 아래), 클라이언트가 프로그래매틱하게 확인할 수 있어요. 그래서 각 응답을 서빙한 환경의 정책, CPU, GPU, 소프트웨어에 대한 증거를 조사할 수 있죠.

무엇이 검사되는지 전체 목록과 조사 방법은 Verifying Your Deployment를 참조하세요.

증명 실패 처리

검증에 실패하면 Cohere OHTTP 프록시는 연결을 거부해요. 요청을 보내지 않으므로 데이터가 검증되지 않은 환경에 노출되지 않아요. 일반적인 원인으로는 잘못된 토큰 서명, 정책 불일치(측정된 소프트웨어가 승인된 스택과 다름), 만료된 토큰, 증명된 환경에 바인딩되지 않은 암호화 키가 있어요.

이런 경우 Model Vault 앱에서 볼트 상태를 확인하고, 검증이 계속 실패하면 Cohere 지원에 연락하세요. 각 실패가 무엇을 의미하는지는 Verifying Your Deployment를 참조하세요.

데모용 호스티드 Cohere OHTTP 프록시

Cohere는 위에서 설명한 클라이언트 측 옵션을 실행하지 않고 표준 볼트처럼 Encrypted 볼트와 상호작용할 수 있게 해 주는 호스티드 OHTTP 프록시도 제공해요. 이 옵션은 프록시 계층을 Cohere와 신뢰해야 하므로 보안 모델이 바뀌기 때문에, 엄격하게 데모 용도로만 의도된 것이에요. 호스티드 OHTTP 프록시를 사용하려면 표준 볼트처럼 Encrypted 볼트에 요청을 보내고 모든 요청에 다음 헤더를 포함하세요:

"X-Cohere-Demo-Encrypt": "1"

Note

보안상 호스티드 OHTTP 프록시는 기본적으로 비활성화되어 있어요. 볼트에 대해 이를 활성화하려면 우리에게 연락해 주세요.

더 알아보기 (Learn more)

Cohere 문서

API로 Encrypted Vault 호출하기