Skip to content

Commit d039838

Browse files
committed
docs: document the request-id header, cacheHitRate, and Vercel routing in every locale
Three more surfaces where shipped behavior had no documentation, or had it only in English. x-opencodex-request-id and cacheHitRate had zero docs-site coverage in any language. The request id is the key that ties a response to its request-log and usage rows; the header is proxy-generated, overwrites any caller or upstream value, and is CORS-exposed so browser clients can actually read it. cacheHitRate is null rather than 0 when a provider reports no cache telemetry, and that distinction matters: 'no data' and 'a real 0% hit rate' are different facts. vercelGatewayRouting was English-only and is now ported to all seven locales.
1 parent 2ee5c7d commit d039838

23 files changed

Lines changed: 398 additions & 4 deletions

File tree

‎docs-site/src/content/docs/fr/reference/configuration/providers.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ sauvegarde dont le contenu diffère, puis réécrit en identifiants sans préfix
9191
| `headers?` | `Record<string, string>` | En-têtes supplémentaires en amont. L'autorisation, les cookies, les en-têtes de clé API, les nouvelles lignes intégrées et les noms invalides sont rejetés. |
9292
| `openRouterRouting?` | `OpenRouterProviderRouting` | Préférences OpenRouter `order`, `only` et `allowFallbacks` par défaut ; valable uniquement pour les OpenRouter canoniques avec `openai-chat`. |
9393
| `modelOpenRouterRouting?` | `Record<string, OpenRouterProviderRouting>` | Remplacements exacts de l'ID de modèle qui remplacent la préférence OpenRouter à l'échelle du fournisseur. |
94+
| `vercelGatewayRouting?` | `VercelGatewayRouting` | Préférences Vercel AI Gateway par défaut pour `order`, `only` et `sort` (`"cost"` \| `"ttft"` \| `"tps"`) ; valables uniquement pour le fournisseur Vercel AI Gateway canonique avec `openai-chat`. |
9495
| `authMode?` | `"key" \| "forward" \| "oauth" \| "local"` | Mode d'authentification (`key` par défaut). Les identifiants OAuth ou d'abonnement sont stockés hors de `config.json` ; `local` est réservé aux fournisseurs dont l'entrée de registre l'autorise. |
9596
| `codexAccountMode?` | `"pool" \| "direct"` | Réservé au fournisseur canonique `openai` ; la valeur par défaut est Pool. Le mode Direct contourne l'état du pool. |
9697
| `refreshPolicy?` | `"proactive" \| "lazy-only" \| "disabled"` | Remplace la politique Token Guardian de ce fournisseur OAuth. |
@@ -371,6 +372,45 @@ Les clés de modèle sont les identifiants OpenRouter natifs exacts, sans le pr
371372
`openrouter/anthropic-claude-sonnet-5` restaure l'identifiant natif `anthropic/claude-sonnet-5` avant d'appliquer
372373
la règle du modèle.
373374

375+
## Routage des fournisseurs Vercel AI Gateway
376+
377+
Vercel AI Gateway peut router un modèle entre plusieurs fournisseurs d'inférence sous-jacents.
378+
`vercelGatewayRouting` configure les préférences à l'échelle du fournisseur ; `modelVercelGatewayRouting` les remplace
379+
pour les identifiants de modèle exacts. Lorsque les deux sont omis, `resolveVercelGatewayRouting()` renvoie `undefined`.
380+
Les générateurs de requêtes Chat omettent alors le champ `provider`, et Vercel AI Gateway conserve son comportement de
381+
routage dynamique par défaut.
382+
383+
- `order` : identifiants courts des fournisseurs en amont de Vercel AI Gateway, par ordre de priorité.
384+
- `only` : liste d'autorisation explicite limitant les fournisseurs en amont de Vercel AI Gateway admissibles.
385+
- `sort` : trie automatiquement les fournisseurs admissibles par `"cost"` (coût le plus faible), `"ttft"` (délai
386+
avant le premier jeton) ou `"tps"` (jetons par seconde).
387+
388+
```json
389+
{
390+
"providers": {
391+
"vercel-ai-gateway": {
392+
"adapter": "openai-chat",
393+
"baseUrl": "https://ai-gateway.vercel.sh/v1",
394+
"apiKey": "${VERCEL_AI_GATEWAY_KEY}",
395+
"vercelGatewayRouting": {
396+
"sort": "ttft"
397+
},
398+
"modelVercelGatewayRouting": {
399+
"zai/glm-5.2": {
400+
"only": ["novita", "deepinfra"],
401+
"order": ["novita", "deepinfra"]
402+
}
403+
}
404+
}
405+
}
406+
}
407+
```
408+
409+
Les clés de modèle sont les sélecteurs de modèle publics de Vercel, sans le préfixe externe du fournisseur OpenCodex.
410+
La sélection de `vercel-ai-gateway/zai-glm-5.2` restaure l'identifiant natif `zai/glm-5.2` avant d'appliquer la règle du
411+
modèle. Le même mappage s'applique à un sélecteur natif `vercel/<model-id>` : utilisez le sélecteur encodé
412+
`vercel-ai-gateway/vercel-<model-id>` dans OpenCodex et conservez `vercel/<model-id>` comme clé de modèle.
413+
374414
## Listes autorisées de modèles statiques
375415

376416
Réglez `liveModels: false` pour exposer uniquement `models`. Si `models` est vide ou omis, le fournisseur n'expose

‎docs-site/src/content/docs/fr/reference/management-api.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,12 @@ réestimée d'après la tarification active au moment de la lecture du résumé.
143143
et non de frais d'abonnement. Les nouvelles requêtes du pool principal utilisent le libellé réservé `main` ; les anciennes lignes
144144
`openai` sans qualification restent dans une catégorie ambiguë au lieu d'être réaffectées d'après la configuration actuelle.
145145

146+
Les lignes de `models`, `providers` et `days[].models` comportent également `cacheHitRate` : la part des jetons
147+
d'entrée servis depuis le cache d'invites du fournisseur, limitée à `[0, 1]`. Cette valeur est `null` — jamais `0` —
148+
lorsque le fournisseur n'a transmis aucune télémétrie de cache ou que la ligne ne contient aucun jeton d'entrée, car
149+
« aucune donnée de cache » et « un véritable taux de succès de 0 % » sont deux faits distincts, et un graphique qui
150+
les représente de la même manière est trompeur.
151+
146152
:::caution
147153
Les points de terminaison de nettoyage du stockage peuvent déplacer ou supprimer définitivement les données de session archivées. Toujours prévisualiser
148154
d’abord et soumettez le résumé renvoyé. Préférez la quarantaine lorsqu’une récupération peut être nécessaire.

‎docs-site/src/content/docs/fr/reference/proxy-formats.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,22 @@ Lorsqu'il est disponible, `input_tokens_details` peut également inclure `cache_
9696
les objets de détail constituent une garantie de compatibilité pour les clients Responses stricts ; zéro peut signifier « non
9797
signalé », pas nécessairement « le prestataire n’a effectué aucun travail de ce type ».
9898

99+
### Corréler une réponse avec son journal de requête
100+
101+
Chaque réponse HTTP Responses admise comporte un en-tête `x-opencodex-request-id` contenant un identifiant généré
102+
par le proxy sous la forme `ocx-<32 hex>`. C'est la clé qui relie une réponse à sa ligne dans le journal des requêtes
103+
et dans les rapports d'utilisation.
104+
105+
Le proxy génère toujours cette valeur et remplace tout identifiant fourni par l'appelant ou renvoyé par le service en
106+
amont. Elle est donc propre à ce proxy et peut être utilisée en toute confiance comme clé de corrélation. L'en-tête est
107+
nommé dans `Access-Control-Expose-Headers`, ce qui permet au JavaScript du navigateur de le lire entre différentes
108+
origines : sans cela, un en-tête `x-` personnalisé reste invisible pour `response.headers.get()`, même lorsqu'il est
109+
présent sur le réseau.
110+
111+
Les réponses rejetées lors de l'authentification ou de l'admission de l'origine n'atteignent jamais cette couche
112+
d'encapsulation et ne comportent aucun identifiant. L'absence de cet en-tête signifie donc que la requête a été refusée
113+
avant sa journalisation.
114+
99115
### Mise à niveau WebSocket sur le même chemin
100116

101117
Lorsque `websockets` est activé, un client peut mettre à niveau `/v1/responses` au lieu d’ouvrir une requête HTTP POST.

‎docs-site/src/content/docs/ja/reference/configuration/providers.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ account を削除しても mapping は保持され、同じ id を再追加す
7979
| `headers?` | `Record<string, string>` |追加の上流ヘッダー。認証、Cookie、API キー ヘッダー、埋め込まれた改行、および無効な名前は拒否されます。 |
8080
| `openRouterRouting?` | `OpenRouterProviderRouting` |デフォルトの OpenRouter `order`、`only`、および `allowFallbacks` 設定。 `openai-chat` を持つ正規 OpenRouter に対してのみ有効です。 |
8181
| `modelOpenRouterRouting?` | `Record<string, OpenRouterProviderRouting>` |プロバイダー全体の OpenRouter 設定を置き換える正確なモデル ID のオーバーライド。 |
82+
| `vercelGatewayRouting?` | `VercelGatewayRouting` |デフォルトの Vercel AI Gateway `order`、`only`、および `sort` (`"cost"` \| `"ttft"` \| `"tps"`) 設定。`openai-chat` を使用する正規の Vercel AI Gateway に対してのみ有効です。 |
8283
| `authMode?` | `"key" \| "forward" \| "oauth" \| "local"` |認証モード (デフォルトは `key`)。 OAuth/サブスクリプション認証情報は `config.json` の外部に保存されます。 `local` は、レジストリ エントリで許可されているプロバイダーに限定されます。 |
8384
| `codexAccountMode?` | `"pool" \| "direct"` |正規の `openai` のみ。デフォルトはプールです。直接はプール状態をバイパスします。 |
8485
| `refreshPolicy?` | `"proactive" \| "lazy-only" \| "disabled"` |この OAuth プロバイダーの Token Guardian ポリシーをオーバーライドします。 |
@@ -297,6 +298,37 @@ OpenRouter は、複数の推論プロバイダーを通じて 1 つのモデル
297298

298299
モデル キーは、外部の opencodex プロバイダー プレフィックスを除いた、正確なネイティブ OpenRouter ID です。 `openrouter/anthropic-claude-sonnet-5` を選択すると、モデル ルールを適用する前のネイティブ `anthropic/claude-sonnet-5` が復元されます。
299300

301+
## Vercel AI Gateway プロバイダーのルーティング
302+
303+
Vercel AI Gateway は、1 つのモデルを複数の基盤となる推論プロバイダーへルーティングできます。`vercelGatewayRouting` はプロバイダー全体の設定を構成し、`modelVercelGatewayRouting` は正確なモデル ID ごとにそれを置き換えます。両方とも未設定の場合、`resolveVercelGatewayRouting()` は `undefined` を返すため、Chat リクエスト ビルダーは `provider` フィールドを省略し、Vercel AI Gateway のデフォルトの動的ルーティング動作が維持されます。
304+
305+
- `order`: 優先順位順の Vercel AI Gateway アップストリーム プロバイダー スラッグ。
306+
- `only`: 対象となる Vercel AI Gateway アップストリーム プロバイダーを制限する明示的な許可リスト。
307+
- `sort`: 対象となるプロバイダーを `"cost"` (最安コスト)、`"ttft"` (最初のトークンまでの時間)、または `"tps"` (1 秒あたりのトークン数) で自動的に並べ替えます。
308+
309+
```json
310+
{
311+
"providers": {
312+
"vercel-ai-gateway": {
313+
"adapter": "openai-chat",
314+
"baseUrl": "https://ai-gateway.vercel.sh/v1",
315+
"apiKey": "${VERCEL_AI_GATEWAY_KEY}",
316+
"vercelGatewayRouting": {
317+
"sort": "ttft"
318+
},
319+
"modelVercelGatewayRouting": {
320+
"zai/glm-5.2": {
321+
"only": ["novita", "deepinfra"],
322+
"order": ["novita", "deepinfra"]
323+
}
324+
}
325+
}
326+
}
327+
}
328+
```
329+
330+
モデル キーは、外側の opencodex プロバイダー プレフィックスを除いた Vercel の公開モデル セレクターです。`vercel-ai-gateway/zai-glm-5.2` を選択すると、モデル ルールを適用する前にネイティブの `zai/glm-5.2` が復元されます。ネイティブの `vercel/<model-id>` セレクターにも同じマッピングが適用されます。opencodex ではエンコードされた `vercel-ai-gateway/vercel-<model-id>` セレクターを使用し、モデル キーには `vercel/<model-id>` を指定してください。
331+
300332
## 静的モデルのホワイトリスト
301333

302334
`models` のみを公開するように `liveModels: false` を設定します。 `models` が空であるか省略されている場合、プロバイダーはルーティングされたモデルを公開しません。ライブ ディスカバリは、キャッシュする前に 4 MiB または 2,000 を超える生のモデル行を拒否します。組み込みのプリセットは下限を使用し、チャットに適した行にフィルターをかけることができます。サイズが大きすぎる、または形式が正しくない結果は、古い/構成されたフォールバックに続きます。ゼロに適格な有効な結果は引き続き権威を持ち、暗黙的に置き換えられたり切り捨てられたりすることはありません。

‎docs-site/src/content/docs/ja/reference/management-api.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,8 @@ Authorization: Bearer <admin-token>
120120
| `POST /api/storage/cleanup-policy/run` |手動クリーンアップ ポリシーの実行を開始します。 409 `already_running`; 500`cleanup_failed` |
121121
| `GET /api/storage/cleanup-policy/test-stream` |テスト専用ポリシー ストリーム フック | 404 `not_found` 利用できない場合 |
122122

123+
`models`、`providers`、および `days[].models` の各行にも `cacheHitRate` が含まれます。これは、プロバイダーのプロンプト キャッシュから供給された入力トークンの割合で、`[0, 1]` の範囲に制限されます。プロバイダーがキャッシュ テレメトリを報告しなかった場合、または行に入力トークンがない場合は、`0` ではなく `null` になります。「キャッシュ データなし」と「実際のヒット率 0%」は異なる事実であり、それらを同じように描画するチャートは誤解を招くためです。
124+
123125
:::caution
124126
ストレージ クリーンアップ エンドポイントは、アーカイブされたセッション データを移動または完全に削除できます。必ず最初にプレビューして、返されたダイジェストを送信してください。回復が必要な場合は隔離を優先します。
125127
:::

‎docs-site/src/content/docs/ja/reference/proxy-formats.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,14 @@ provider events → internal adapter events → client dialect
7373

7474
利用可能な場合、`input_tokens_details` には `cache_write_tokens` も含めることができます。常に存在する詳細オブジェクトは、厳密な応答クライアントに対する互換性を保証します。ゼロは「報告されていない」ことを意味する場合がありますが、必ずしも「プロバイダーがそのような作業を実行していない」とは限りません。
7575

76+
### 応答とリクエストログの関連付け
77+
78+
アドミッションを通過したすべての HTTP Responses 応答には、プロキシが生成した `ocx-<32 hex>` 形式の ID を格納する `x-opencodex-request-id` ヘッダーが付与されます。この値は、応答をリクエストログおよび使用状況レポート内の対応する行に結び付けるキーです。
79+
80+
プロキシは常にこの値を生成し、呼び出し元が指定した ID やアップストリームが返した ID を上書きします。そのため、このプロキシに固有であり、相関キーとして安全に信頼できます。このヘッダーは `Access-Control-Expose-Headers` に列挙されているため、ブラウザーの JavaScript からクロスオリジンで読み取れます。カスタムの `x-` ヘッダーは、実際にワイヤ上に存在していても、そうしなければ `response.headers.get()` からは見えません。
81+
82+
認証またはオリジンのアドミッションで拒否されたリクエストはこのラッパーに到達せず、ID も付与されません。そのため、ヘッダーがない場合は、リクエストがログに記録される前に拒否されたことを意味します。
83+
7684
### 同じパスでの WebSocket のアップグレード
7785

7886
`websockets` が有効な場合、クライアントは HTTP POST を開く代わりに `/v1/responses` をアップグレードできます。認証とオリジンの許可は、WebSocket ハンドシェイク中に行われます。それらは各フレーム内で繰り返されません。

‎docs-site/src/content/docs/ko/reference/configuration/providers.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ managed map을 활성화하면 privacy-safe selector를 만들고, 이후 계정
7979
| `headers?` | `Record<string, string>` | 추가 상위 헤더입니다. Authorization, cookies, API-key 헤더, 내장 개행, 잘못된 이름은 허용하지 않습니다. |
8080
| `openRouterRouting?` | `OpenRouterProviderRouting` | 기본 OpenRouter `order`, `only`, `allowFallbacks` 선호도입니다. 정식 OpenRouter와 `openai-chat`에서만 유효합니다. |
8181
| `modelOpenRouterRouting?` | `Record<string, OpenRouterProviderRouting>` | 공급자 전반의 OpenRouter 선호도를 덮어쓰는 정확한 모델 id별 재정의입니다. |
82+
| `vercelGatewayRouting?` | `VercelGatewayRouting` | 기본 Vercel AI Gateway `order`, `only`, `sort`(`"cost"` \| `"ttft"` \| `"tps"`) 선호도입니다. 정식 Vercel AI Gateway와 `openai-chat`에서만 유효합니다. |
8283
| `authMode?` | `"key" \| "forward" \| "oauth" \| "local"` | 인증 모드입니다. 기본값은 `key`입니다. OAuth/구독 자격 증명은 `config.json` 밖에 저장되며, `local`은 레지스트리 항목이 허용하는 공급자에서만 사용할 수 있습니다. |
8384
| `codexAccountMode?` | `"pool" \| "direct"` | 정식 `openai` 전용입니다. 기본값은 Pool입니다. Direct는 풀 상태를 우회합니다. |
8485
| `refreshPolicy?` | `"proactive" \| "lazy-only" \| "disabled"` | 이 OAuth 공급자의 Token Guardian 정책을 덮어씁니다. |
@@ -298,6 +299,43 @@ OpenRouter는 하나의 모델을 여러 추론 공급자로 제공할 수 있
298299

299300
모델 키는 외부 opencodex 공급자 접두사 없이, 정확한 네이티브 OpenRouter id여야 합니다. `openrouter/anthropic-claude-sonnet-5`를 선택하면 모델 규칙을 적용하기 전에 네이티브 `anthropic/claude-sonnet-5`로 되돌아갑니다.
300301

302+
## Vercel AI Gateway 공급자 라우팅
303+
304+
Vercel AI Gateway는 하나의 모델을 여러 기반 추론 공급자에 걸쳐 라우팅할 수 있습니다. `vercelGatewayRouting`은
305+
공급자 전반의 선호도를 구성하고, `modelVercelGatewayRouting`은 정확한 모델 ID에 대해 이를 대체합니다. 둘 다
306+
설정하지 않으면 `resolveVercelGatewayRouting()`이 `undefined`를 반환하므로 Chat 요청 빌더는 `provider` 필드를
307+
생략하고 Vercel AI Gateway의 기본 동적 라우팅 동작이 유지됩니다.
308+
309+
- `order`: Vercel AI Gateway 업스트림 공급자 slug를 우선순위 순으로 지정합니다.
310+
- `only`: 사용할 수 있는 Vercel AI Gateway 업스트림 공급자를 제한하는 명시적 허용 목록입니다.
311+
- `sort`: 사용할 수 있는 공급자를 `"cost"`(최저 비용), `"ttft"`(첫 토큰까지 걸리는 시간), `"tps"`(초당 토큰 수) 기준으로 자동 정렬합니다.
312+
313+
```json
314+
{
315+
"providers": {
316+
"vercel-ai-gateway": {
317+
"adapter": "openai-chat",
318+
"baseUrl": "https://ai-gateway.vercel.sh/v1",
319+
"apiKey": "${VERCEL_AI_GATEWAY_KEY}",
320+
"vercelGatewayRouting": {
321+
"sort": "ttft"
322+
},
323+
"modelVercelGatewayRouting": {
324+
"zai/glm-5.2": {
325+
"only": ["novita", "deepinfra"],
326+
"order": ["novita", "deepinfra"]
327+
}
328+
}
329+
}
330+
}
331+
}
332+
```
333+
334+
모델 키는 외부 OpenCodex 공급자 접두사가 없는 Vercel 공개 모델 선택자입니다.
335+
`vercel-ai-gateway/zai-glm-5.2`를 선택하면 모델 규칙 적용 전에 네이티브 `zai/glm-5.2`가 복원됩니다. 네이티브
336+
`vercel/<model-id>` 선택자에도 동일한 매핑이 적용됩니다. OpenCodex에서는 인코딩된
337+
`vercel-ai-gateway/vercel-<model-id>` 선택자를 사용하고, 모델 키에는 `vercel/<model-id>`를 유지하십시오.
338+
301339
## 정적 모델 허용 목록
302340

303341
`liveModels: false`로 두면 `models`만 노출합니다. `models`가 비어 있거나 생략되면 공급자는 어떤 라우팅 모델도 노출하지 않습니다. 라이브 발견은 캐싱 전에 4 MiB 또는 원시 모델 행 2,000개를 넘으면 거부합니다. 내장 프리셋은 더 낮은 한도를 쓰고 chat 가능한 행만 필터링할 수 있습니다. 너무 크거나 형식이 잘못된 결과는 오래된/설정된 폴백을 따릅니다. 유효하지만 선택 가능한 항목이 0개인 결과는 그대로 권위가 있으며, 조용히 다른 값으로 바꾸거나 잘라내지 않습니다.

0 commit comments

Comments
 (0)