docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials - #249
Merged
Merged
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughLarge-scale documentation rebuild: removes legacy docs and adds a structured docs site with new overview, quickstarts, configuration, integrations, cloud operations, references, tutorials, and README adjustments. No source code changes. ChangesDocumentation Restructure
Sequence Diagram(s)(skipped) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~30 minutes |
There was a problem hiding this comment.
Pull request overview
This PR rebuilds the repository documentation structure (new landing/overview/quickstart/roadmap pages and removal of legacy flat docs). It also introduces functional changes to the gateway’s cross-provider tool-calling translation (Anthropic ↔ OpenAI shapes) and adds an E2E test that pins the expected behavior.
Changes:
- Replaces legacy docs pages with a new docs IA: landing page, overview pages, roadmap, and self-hosted quickstart.
- Adds E2E coverage for OpenAI-tools → Anthropic-tools/tool_use → OpenAI-tool_calls translation.
- Updates Rust proxy/provider code to forward
tool_callsviamessage.extraand to translate OpenAItoolsinto Anthropic’stoolsshape.
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/e2e/src/cases/tools-cross-provider-e2e.test.ts | Adds a new E2E scenario covering cross-provider tool translation. |
| docs/index.md | New docs landing page and navigation structure. |
| docs/roadmap.md | New roadmap page to contain planned/incomplete capabilities. |
| docs/overview/what-is-aisix-ai-gateway.md | New “what is” overview page. |
| docs/overview/deployment-modes.md | New overview comparing self-hosted vs Cloud managed DP. |
| docs/overview/core-concepts.md | New glossary of core entities and boundaries. |
| docs/overview/feature-matrix.md | New capability/status matrix for Gateway vs Cloud. |
| docs/quickstart/self-hosted.md | New quickstart for bootstrapping a self-hosted gateway. |
| docs/testing.md | Removes legacy testing doc page. |
| docs/managed-mode.md | Removes legacy managed-mode doc page. |
| docs/architecture.md | Removes legacy architecture doc page. |
| docs/api-proxy.md | Removes legacy proxy API doc page. |
| docs/api-admin.md | Removes legacy admin API doc page. |
| crates/aisix-proxy/src/render.rs | Extends rendered OpenAI message shape to flatten message.extra onto the wire (e.g., tool_calls). |
| crates/aisix-provider-anthropic/src/wire.rs | Implements OpenAI-tools → Anthropic-tools translation and Anthropic tool_use → OpenAI tool_calls response mapping. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - `gemini` | ||
| - `deepseek` | ||
|
|
||
| Provider support is not identical across every endpoint. See [Provider Compatibility](../reference/provider-compatibility.md) for the current matrix. |
Comment on lines
+66
to
+73
| See [AISIX Cloud Overview](../cloud/overview.md) and [Cloud Playground](../cloud/cloud-playground.md) for details. | ||
|
|
||
| ## Related Pages | ||
|
|
||
| - [What Is AISIX AI Gateway](what-is-aisix-ai-gateway.md) | ||
| - [Core Concepts](core-concepts.md) | ||
| - [AISIX Cloud Overview](../cloud/overview.md) | ||
| - [AISIX Cloud Managed Data Plane Quickstart](../quickstart/aisix-cloud-managed-dp.md) |
Comment on lines
+88
to
+94
| ```json | ||
| { | ||
| "status": "ok", | ||
| "models": 0, | ||
| "apikeys": 0, | ||
| "providers": 0 | ||
| } |
Comment on lines
+14
to
+21
| // E2E: tool / function calling cross-provider translation. Per | ||
| // gateway docs `docs/api-proxy.md` §6 outbound-axis table: | ||
| // | ||
| // > Anthropic | /v1/messages | /v1/chat/completions (full translation) | ||
| // > | The Hub maps content blocks ↔ messages, **tool_use ↔ tool_calls**, | ||
| // > | system extraction, cache_control passthrough, stop_reason | ||
| // > | normalisation | ||
| // |
Comment on lines
+239
to
+245
| /// and `input` is a JSON object with the tool's arguments. Per | ||
| /// docs §6 outbound-axis table ("tool_use ↔ tool_calls"), the | ||
| /// gateway translates this into OpenAI's `tool_calls` shape on | ||
| /// the response so OpenAI-SDK callers (and every agent framework | ||
| /// built on that shape) work transparently against Anthropic | ||
| /// upstreams. | ||
| /// <https://docs.anthropic.com/en/api/messages#example-of-tool-use> |
Comment on lines
30
to
+33
| pub struct RenderedMessage { | ||
| pub role: &'static str, | ||
| pub content: String, | ||
| /// Forward-compatible bag for OpenAI message-level fields the |
| "type": "function", | ||
| "function": { | ||
| "name": name, | ||
| "arguments": serde_json::to_string(input).unwrap_or_default(), |
Comment on lines
+1
to
+7
| --- | ||
| title: AISIX AI Gateway Documentation | ||
| description: Official documentation for AISIX AI Gateway and AISIX Cloud, including quickstarts, integration guides, configuration, operations, API reference, and roadmap. | ||
| sidebar_position: 1 | ||
| --- | ||
|
|
||
| AISIX AI Gateway is an AI gateway for platform engineers and AI agent developers who need a consistent way to route, govern, and observe LLM traffic across multiple providers. AISIX Cloud extends that gateway with a managed control plane and managed data-plane workflows. |
Comment on lines
+14
to
+20
| // E2E: tool / function calling cross-provider translation. Per | ||
| // gateway docs `docs/api-proxy.md` §6 outbound-axis table: | ||
| // | ||
| // > Anthropic | /v1/messages | /v1/chat/completions (full translation) | ||
| // > | The Hub maps content blocks ↔ messages, **tool_use ↔ tool_calls**, | ||
| // > | system extraction, cache_control passthrough, stop_reason | ||
| // > | normalisation |
Comment on lines
+95
to
+97
| | `request_body_limit_bytes` | request-body limit enforced by the proxy listener | | ||
| | `tls` | optional TLS certificate and key for the proxy listener | | ||
|
|
| "type": "function", | ||
| "function": { | ||
| "name": name, | ||
| "arguments": serde_json::to_string(input).unwrap_or_default(), |
moonming
changed the title
| | Field | Description | | ||
| | --- | --- | | ||
| | `addr` | proxy listener address | | ||
| | `request_body_limit_bytes` | request-body limit enforced by the proxy listener | |
Comment on lines
+33
to
+53
| ```ts title="openai-sdk-example.ts" | ||
| import OpenAI from "openai"; | ||
|
|
||
| const client = new OpenAI({ | ||
| apiKey: process.env.AISIX_API_KEY, | ||
| baseURL: "http://127.0.0.1:3000/v1", | ||
| }); | ||
|
|
||
| const response = await client.chat.completions.create({ | ||
| model: "gpt-4o-prod", | ||
| messages: [{ role: "user", content: "Say hello from AISIX." }], | ||
| }); | ||
|
|
||
| console.log(response.choices[0]?.message.content); | ||
| ``` | ||
|
|
||
| ## Run It | ||
|
|
||
| ```bash title="Run the OpenAI SDK example" | ||
| AISIX_API_KEY=sk-demo-caller node openai-sdk-example.ts | ||
| ``` |
| - **Observability** — Prometheus `/metrics`; per-request structured access log; per-env `ObservabilityExporter` (`kind=otlp_http`) fan-out emitting one OTLP/HTTP-JSON GenAI span per chat completion to each enabled exporter (Langfuse, Honeycomb, Grafana Cloud, any OTLP receiver). Platform-level OTLP tracing of internal request-pipeline spans is scaffold ([#49]). | ||
|
|
||
| - **Telemetry events** — DP-side `UsageEvent` per request with cache_status, reasoning, provider-id detail, guardrail bypass reason, and `inbound_protocol` (`"openai"` / `"anthropic"`) so dashboard Logs disambiguate the SDK from the upstream `provider` label. Emitted by `/v1/chat/completions` and `/v1/messages` (passthrough-streaming and other endpoints land in a follow-up). Posted to cp-api in managed mode; consumed by `/admin/v1/spend` in standalone. | ||
| - **Telemetry events** — DP-side `UsageEvent` per request with cache_status, reasoning, provider-id detail, guardrail bypass reason, and `inbound_protocol` (`"openai"` / `"anthropic"`) so dashboard logs can disambiguate the client protocol from the upstream `provider` label. Emitted by `/v1/chat/completions` and `/v1/messages`; posted to cp-api in managed mode. |
This was referenced May 14, 2026
moonming
force-pushed
the
docs-rebuild-batch-1
branch
from
May 14, 2026 00:43
10cc683 to
002db0d
Compare
moonming
force-pushed
the
docs-rebuild-batch-1
branch
from
May 14, 2026 01:09
002db0d to
86b9a1f
Compare
- quickstart/self-hosted: document the /livez liveness route and plain-text body (per #257); add Cleanup - quickstart/openai-sdk: switch to .mjs so \`node\` runs the example without a TypeScript loader - quickstart/first-model-first-key-first-request: add production-credentials warning, 401/403 verification step using the real proxy error envelope, Cleanup, and a per-provider api_base callout - integration/openai-compatible-api: add mermaid diagram of the request path; route list reflects the /livez rename - integration/errors-and-retries: replace placeholder error.type strings with the real ProxyError mapping; add 413 RequestTooLarge row; note the admin {error_msg} envelope distinction - configuration/provider-keys: warn about plaintext secret storage; replace the inaccurate OpenAI api_base normalization claim with a per-provider truth table (refs #270) - operations/health-checks: rewrite for the /livez liveness contract plus the /admin/v1/health per-model shape (per #256 + #257) - reference/proxy-api-reference: /livez instead of /health in the route list - tutorials/build-a-virtual-model-with-failover: rewrite end-to-end against routing-strategies-e2e (deliberately break primary, observe cooldown) - tutorials/enable-response-caching: rewrite against cache-policy-e2e (x-aisix-cache miss then hit, different prompt misses again) - tutorials/add-keyword-guardrails: rewrite against guardrail-keyword-e2e (422 content_filter; no-leak message contract per #203) - tutorials/openai-client-to-anthropic-upstream: rewrite against anthropic-upstream-e2e; document bare-host api_base for Anthropic Every command, field, header, and error code was cross-checked against the relevant crate or e2e test on this branch. No mock data; nothing speculative.
moonming
force-pushed
the
docs-rebuild-batch-1
branch
from
May 14, 2026 01:19
86b9a1f to
bc8c9d1
Compare
This was referenced May 14, 2026
Closed
Closed
This was referenced May 15, 2026
Closed
Merged
Merged
docs: Configuration reference corrections across admin-api, api-keys, caching, and models pages
#347
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/set into a new customer-facing structure forAISIX AI GatewayandAISIX Clouddocs/roadmap.mdREADME.mdwith the current docs entry points and runtime boundariesCompleted In This PR
Docs Added Or Rebuilt
docs/index.mddocs/roadmap.mddocs/overview/*docs/quickstart/self-hosted.mddocs/quickstart/first-model-first-key-first-request.mddocs/integration/openai-compatible-api.mddocs/configuration/*docs/cloud/*docs/operations/*docs/reference/*docs/tutorials/*README.mdIssue Coverage
Completed:
#245landing page, overview, feature matrix, and roadmap#248gateway configuration docs#242operations docs#244reference docs#247AISIX Cloud docs#241scenario-driven tutorials#201admin docs gap for guardrails, cache policies, and observability exportersPartially completed:
#243quickstartsself-hosted,first-model-first-key-first-requestopenai-sdk,anthropic-sdk,aisix-cloud-managed-dp#246integration guidesopenai-compatible-apiNotes
Summary by CodeRabbit