diff --git a/English/.gitbook/assets/image (1086).png b/English/.gitbook/assets/image (1086).png new file mode 100644 index 000000000..59311db41 Binary files /dev/null and b/English/.gitbook/assets/image (1086).png differ diff --git a/English/SUMMARY.md b/English/SUMMARY.md index 1834b300d..0fe239183 100644 --- a/English/SUMMARY.md +++ b/English/SUMMARY.md @@ -751,21 +751,15 @@ * [Model Pricing List](ai-stack/model-as-a-service/model-pricing-list.md) * [AI Gateway](ai-stack/ai-gateway/README.md) * [What is AI Gateway?](ai-stack/ai-gateway/what-is-ai-gateway.md) - * [Get starting with AI Gateway](ai-stack/ai-gateway/get-starting-with-ai-gateway/README.md) - * [Initialize AI Gateway](ai-stack/ai-gateway/get-starting-with-ai-gateway/initialize-ai-gateway.md) - * [Sending Requests to AI Gateway](ai-stack/ai-gateway/get-starting-with-ai-gateway/sending-requests-to-ai-gateway.md) - * [Monitoring AI Gateway Activity](ai-stack/ai-gateway/get-starting-with-ai-gateway/monitoring-ai-gateway-activity.md) - * [AI Gateway](ai-stack/ai-gateway/ai-gateway/README.md) + * [Get Started with AI Gateway](ai-stack/ai-gateway/get-starting-with-ai-gateway/README.md) * [Initialize AI Gateway](ai-stack/ai-gateway/ai-gateway/initialize-ai-gateway.md) - * [Working with Providers and Models](ai-stack/ai-gateway/ai-gateway/working-with-providers-and-models/README.md) - * [Model Providers](ai-stack/ai-gateway/ai-gateway/working-with-providers-and-models/model-providers.md) - * [Seft-host Models](ai-stack/ai-gateway/ai-gateway/working-with-providers-and-models/seft-host-models.md) * [Sending Requests to AI Gateway](ai-stack/ai-gateway/ai-gateway/sending-requests-to-ai-gateway.md) - * [Working with Authentication Tokens](ai-stack/ai-gateway/ai-gateway/working-with-authentication-tokens.md) - * [Caching](ai-stack/ai-gateway/ai-gateway/caching.md) - * [Guardrails (Coming soon)](ai-stack/ai-gateway/ai-gateway/guardrails-coming-soon.md) - * [Rate Limit](ai-stack/ai-gateway/ai-gateway/rate-limit.md) - * [Monitoring AI Gateway Activity](ai-stack/ai-gateway/monitoring-ai-gateway-activity.md) + * [Monitoring AI Gateway Activity](ai-stack/ai-gateway/monitoring-ai-gateway-activity.md) + * [Working with Providers and Models](ai-stack/ai-gateway/ai-gateway/working-with-providers-and-models/README.md) + * [Model Providers](ai-stack/ai-gateway/ai-gateway/working-with-providers-and-models/model-providers.md) + * [Working with Authentication Tokens](ai-stack/ai-gateway/ai-gateway/working-with-authentication-tokens.md) + * [Caching](ai-stack/ai-gateway/ai-gateway/caching.md) + * [Rate Limit](ai-stack/ai-gateway/ai-gateway/rate-limit.md) * [Security](ai-stack/ai-gateway/security.md) * [Pricing](ai-stack/ai-gateway/pricing.md) * [Token Plan](ai-stack/token-plan/README.md) @@ -782,7 +776,6 @@ * [OpenCode](ai-stack/ai-coding/cli-tools/opencode.md) * [GUI Tools](ai-stack/ai-coding/gui-tools/README.md) * [Codex Desktop](ai-stack/ai-coding/gui-tools/codex-desktop.md) - * [GenAI Studio](ai-stack/genai-studio.md) * [GreenNode AgentBase](ai-stack/agent-base/README.md) * [Getting Started](ai-stack/agent-base/getting-started.md) * [Manage AgentBase with the GreenNode CLI](ai-stack/agent-base/manage-agentbase-with-the-greennode-cli.md) diff --git a/English/ai-stack/README.md b/English/ai-stack/README.md index 8262d96f2..4f1bf33c4 100644 --- a/English/ai-stack/README.md +++ b/English/ai-stack/README.md @@ -1,7 +1,61 @@ # AI Stack -GreenNode AI Stack is a comprehensive suite of AI infrastructure services designed to help you build, deploy, and manage AI applications and agents on the cloud. +## Overview -| Service | Description | -| --- | --- | -| [Agent Base](agent-base/README.md) | Infrastructure platform for deploying and managing AI Agents | +GreenNode provides a comprehensive AI platform that helps enterprises deploy, integrate, and operate Generative AI applications easily, securely, and efficiently. The GreenNode AI Stack is designed to be modular and flexible, optimized for both engineering teams and business leaders. + +
+ +*** + +## Core Components + +#### 1. Flexible AI infrastructure with VKS + +* **VKS (GreenNode Kubernetes Service)** is a fully managed Kubernetes service. +* Integrated GPU support, autoscaling, resource monitoring, and security. +* Optimized for AI workloads that require GPU, and equally suitable for deploying web applications, microservices, and large-scale backends. +* Lets enterprises deploy applications quickly without building and maintaining their own infrastructure. + +#### 2. Vector Database as a service + +* Supports PostgreSQL (**pgvector**) and **OpenSearch** as vector databases. +* Delivered as a **managed service** — no infrastructure to manage. +* Enables rapid deployment of **RAG (Retrieval-Augmented Generation)** architectures. +* Helps GenAI models understand and use enterprise data in context. + +#### 3. Comprehensive AI Platform + +* Provides an environment to **experiment (notebook)**, **fine-tune**, and run **inference** on AI models directly on GreenNode GPU infrastructure. +* Integrates with storage services such as **vStorage** to store training data, model registry, and outputs. +* **Fine-tune** capabilities are currently under development (coming soon). +* Lowers technical barriers and shortens time to deployment. + +#### 4. vStorage – Efficient AI storage + +* **vStorage** is an **S3-compatible object storage** service optimized for AI workloads. +* Suitable for storing training data, model checkpoints, model registry, and inference output. +* Integrates easily with components such as AI Platform, VKS, and popular training tools. + +#### 5. AI Gateway – Centralized routing and monitoring + +* A single access point for multiple AI models, with intelligent routing and caching to optimize performance and cost. +* Tracks access, generates audit logs, and monitors usage behavior through metrics and alerts. +* Integrates guardrails to control content and keep AI safe in production. + +#### 6. Model-as-a-Service + +* Provides access to a wide range of leading **GenAI models** such as GPT, Claude, Gemini, and DeepSeek through a single unified API. +* Includes both open-source models and models optimized for Vietnamese. +* The service is currently being finalized (coming soon). +* Shortens integration time so enterprises can experiment and bring AI into production quickly. + +*** + +#### Core Value for Enterprises + +* Accelerate the GenAI adoption journey without a dedicated in-house AI team. +* Remove infrastructure overhead and optimize AI operating costs. +* Strengthen control, security, and flexibility when integrating AI into digital products. + +The GreenNode AI Stack is an ideal foundation for enterprises to build and scale GenAI applications safely, efficiently, and sustainably. diff --git a/English/ai-stack/agent-base/access-control/README.md b/English/ai-stack/agent-base/access-control/README.md index 4f218daac..acb9eafe2 100644 --- a/English/ai-stack/agent-base/access-control/README.md +++ b/English/ai-stack/agent-base/access-control/README.md @@ -11,7 +11,7 @@ ### What Is an Identity? -In AgentBase, an **Identity** is a named, platform-managed record that uniquely represents your agent within the organization. Think of it as the agent's "account" — the foundation on which everything else is built. An identity must exist before a Runtime can be created for that agent, and before any auth credentials can be retrieved. +In AgentBase, an **Identity** is a named, platform-managed record that uniquely represents your agent within the organization. Think of it as the agent's "account" — the foundation on which everything else is built. An identity must exist before a Runtime can be created for that agent, and before any auth credentials can be retrieved. **An identity has:** @@ -21,7 +21,7 @@ In AgentBase, an **Identity** is a named, platform-managed record that uniquely **Identity naming rules:** -* 3–50 characters +* 3–50 characters * Alphanumeric, underscore `_`, and hyphen `-` only (`^[a-zA-Z0-9_-]+$`) * Must be unique within the organization @@ -31,20 +31,20 @@ An Identity is persistent and environment-agnostic. A Runtime is tied to a speci ``` Identity: my-order-agent (persistent) - │ - ├─── Runtime: my-order-agent-staging (environment-specific) - └─── Runtime: my-order-agent-prod (environment-specific) + │ + ├─── Runtime: my-order-agent-staging (environment-specific) + └─── Runtime: my-order-agent-prod (environment-specific) ``` ### Outbound Authentication -When your agent calls external services (OpenAI, Google, Slack, internal APIs), it needs credentials. AgentBase's Auth system lets you store these credentials centrally and have them automatically delivered to your agent at runtime — without hardcoding them. +When your agent calls external services (OpenAI, Google, Slack, internal APIs), it needs credentials. AgentBase's Auth system lets you store these credentials centrally and have them automatically delivered to your agent at runtime — without hardcoding them. The auth system supports three credential types: -* **Static API Key** — A fixed string (such as an API key) associated with an identity. Use when the external service issues a long-lived API key and you want centralized management. -* **Delegated API Key** — A credential that is scoped and potentially short-lived, useful for multi-tenant scenarios where different agents should get different scoped keys. -* **OAuth2 Provider** — For services that use OAuth2 (Google, Slack, and others). AgentBase stores the client credentials and refresh token, and handles token refresh automatically. +* **Static API Key** — A fixed string (such as an API key) associated with an identity. Use when the external service issues a long-lived API key and you want centralized management. +* **Delegated API Key** — A credential that is scoped and potentially short-lived, useful for multi-tenant scenarios where different agents should get different scoped keys. +* **OAuth2 Provider** — For services that use OAuth2 (Google, Slack, and others). AgentBase stores the client credentials and refresh token, and handles token refresh automatically. | Provider Type | Use Case | Storage | | --------------------- | -------------------------------------------------- | ------------------------- | @@ -65,7 +65,7 @@ The auth system supports three credential types: 1. Open https://aiplatform.console.greennode.ai/access-control 2. Click **"Create Identity"** 3. Fill in: - * **Name** (required): e.g., `my-order-agent` — lowercase, alphanumeric and hyphens + * **Name** (required): e.g., `my-order-agent` — lowercase, alphanumeric and hyphens * **Description** (optional): e.g., `Handles order inquiries` * **Allowed Return URLs** (optional): OAuth2 callback URLs for this identity 4. Click **Create** @@ -98,7 +98,7 @@ The auth system supports three credential types: ### RESTful API -> **Prerequisite:** All API examples below use `$TOKEN` — an IAM bearer token. See [Configure Authentication](../getting-started.md#configure-authentication) for how to obtain it. +> **Prerequisite:** All API examples below use `$TOKEN` — an IAM bearer token. See [Configure Authentication](../getting-started.md#configure-authentication) for how to obtain it. #### Create an Identity @@ -126,7 +126,7 @@ curl -s -X POST "https://agentbase.api.vngcloud.vn/identity/api/v1/agent-identit } ``` -**Error: 409 Conflict** — name already exists. Choose a different name or use the existing identity. +**Error: 409 Conflict** — name already exists. Choose a different name or use the existing identity. #### List Identities @@ -264,7 +264,7 @@ An **agent identity** must exist before creating auth providers. If you haven't 1. Open https://aiplatform.console.greennode.ai/access-control → **Auth Providers** 2. Click **"Create Provider"** → select **"OAuth2"** 3. Fill in: **Name**, **Client ID**, **Client Secret**, **Authorization URL**, **Token URL** -4. Click **Create** — the response includes a **Callback URL** to register in your OAuth2 app +4. Click **Create** — the response includes a **Callback URL** to register in your OAuth2 app ![1774593811794](../../../.gitbook/assets/1774593811794.png) @@ -367,7 +367,7 @@ curl -s -X POST "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth }' | jq . ``` -**Response includes `callbackUrl` — register this in your OAuth2 app.** +**Response includes `callbackUrl` — register this in your OAuth2 app.** **List:** @@ -541,7 +541,7 @@ def handler(payload: dict, context: RequestContext, google_token: str) -> dict: | 401 Unauthorized | Expired or invalid IAM token | Re-obtain token with valid credentials | | 403 Forbidden | Service account lacks permissions | Attach `AgentBaseFullAccess` at https://iam.console.greennode.ai | | 409 Conflict | Identity or provider name already exists | Choose a different name | -| Name validation error | Name doesn't match `^[a-zA-Z0-9_-]+$` | Use only alphanumeric, underscore, and hyphen. 3–50 chars | +| Name validation error | Name doesn't match `^[a-zA-Z0-9_-]+$` | Use only alphanumeric, underscore, and hyphen. 3–50 chars | | 404 Not Found | Provider name does not exist | Verify with a `list` operation | | Agent can't retrieve credential | Identity name missing | Ensure `GREENNODE_AGENT_IDENTITY` env var is set in the runtime | diff --git a/English/ai-stack/agent-base/agent-runtime/logs-and-metrics.md b/English/ai-stack/agent-base/agent-runtime/logs-and-metrics.md index 779351764..b48a519b2 100644 --- a/English/ai-stack/agent-base/agent-runtime/logs-and-metrics.md +++ b/English/ai-stack/agent-base/agent-runtime/logs-and-metrics.md @@ -49,7 +49,7 @@ Fetch container logs from all replicas of a runtime. Uses offset-based paginatio ### RESTful API -> **Prerequisite:** All API examples below use `$TOKEN` — an IAM bearer token. See [Configure Authentication](../getting-started.md#configure-authentication) for how to obtain it. +> **Prerequisite:** All API examples below use `$TOKEN` — an IAM bearer token. See [Configure Authentication](../getting-started.md#configure-authentication) for how to obtain it. ```bash RUNTIME_ID="" @@ -153,7 +153,7 @@ curl -s "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/en ### Pseudo-Tailing (Poll Pattern) -Log streaming is not supported — use polling to approximate tailing: +Log streaming is not supported — use polling to approximate tailing: ```bash OFFSET=0 @@ -194,18 +194,18 @@ done | CPU | RAM | Diagnosis | | --------- | ------ | ----------------------------------------------------------------------------- | -| High | Normal | CPU-bound workload — scale up or optimize | -| Normal | High | Memory leak or large data structures — scale up or fix leak | -| Both high | — | Resource exhaustion — scale up flavor | -| Both low | — | External bottleneck (LLM API latency, network) — add request timing in logs | +| High | Normal | CPU-bound workload — scale up or optimize | +| Normal | High | Memory leak or large data structures — scale up or fix leak | +| Both high | — | Resource exhaustion — scale up flavor | +| Both low | — | External bottleneck (LLM API latency, network) — add request timing in logs | *** ## What's Supported -* **Log time range filter** — Filter logs by a specific time window (start/end timestamp), so you can narrow down exactly when an issue occurred without fetching the entire log history. -* **Log keyword search** — Search logs by keyword or phrase directly in the query, returning only matching entries without needing to grep locally after fetching. -* **Historical metrics** — Query CPU and RAM usage over a time range, not just the current point-in-time snapshot. Useful for spotting resource trends, spikes, and patterns leading up to an incident. +* **Log time range filter** — Filter logs by a specific time window (start/end timestamp), so you can narrow down exactly when an issue occurred without fetching the entire log history. +* **Log keyword search** — Search logs by keyword or phrase directly in the query, returning only matching entries without needing to grep locally after fetching. +* **Historical metrics** — Query CPU and RAM usage over a time range, not just the current point-in-time snapshot. Useful for spotting resource trends, spikes, and patterns leading up to an incident. *** diff --git a/English/ai-stack/agent-base/agent-runtime/openclaw/deploy-and-manage-openclaw.md b/English/ai-stack/agent-base/agent-runtime/openclaw/deploy-and-manage-openclaw.md index d25f6b1db..882ca98d7 100644 --- a/English/ai-stack/agent-base/agent-runtime/openclaw/deploy-and-manage-openclaw.md +++ b/English/ai-stack/agent-base/agent-runtime/openclaw/deploy-and-manage-openclaw.md @@ -1,6 +1,6 @@ # Deploy & Manage OpenClaw -OpenClaw 1-Click lets you deploy a personal AI Agent on GreenNode Agentbase in 40–60 seconds, automatically connected to GreenNode MaaS with no manual configuration required. +OpenClaw 1-Click lets you deploy a personal AI Agent on GreenNode Agentbase in 40–60 seconds, automatically connected to GreenNode MaaS with no manual configuration required. For an overview of concepts, architecture, and deployment options, see [OpenClaw 1-Click](openclaw-1-click.md). @@ -27,14 +27,14 @@ On the Agent Marketplace, find the **OpenClaw Featured Card** or click **"Deploy The configuration screen has 3 sections: -**Section 1 — AI Source** +**Section 1 — AI Source** Select the AI source for your OpenClaw instance: | Option | Description | Requirement | | ------------------------------- | ------------------------------------------------------ | -------------------------- | | **GreenNode MaaS** (default) | Automatically connects to GreenNode Model-as-a-Service | GreenNode account required | -| **BYOK — Bring Your Own Key** | Use an API key from an external provider | Valid API key required | +| **BYOK — Bring Your Own Key** | Use an API key from an external provider | Valid API key required | When selecting **BYOK**, provide the following additional details: @@ -46,14 +46,14 @@ When selecting **BYOK**, provide the following additional details: **BYOK note:** If the API key is invalid or expired, the system will show an inline error and block submission. Double-check your key before submitting. {% endhint %} -**Section 2 — Instance Configuration** +**Section 2 — Instance Configuration** | Field | Description | Notes | | ----------------- | -------------------------------------------- | ---------------------------------------------------------------------- | | **OpenClaw Name** | Instance identifier | Auto-filled as `openclaw/{username}`, cannot be changed after creation | | **Flavor** | Compute resource configuration (vCPU × RAM) | Default: `2×4`. Options include `4×8`, `8×16`... | -**Section 3 — Channel Configuration (Optional)** +**Section 3 — Channel Configuration (Optional)** Connect OpenClaw to a messaging platform so you can chat right after deployment. @@ -65,7 +65,7 @@ Connect OpenClaw to a messaging platform so you can chat right after deployment. Once all fields are filled, click **"Start Setup"** to begin provisioning. -#### Step 2: Provisioning — Setting Up Your Workspace +#### Step 2: Provisioning — Setting Up Your Workspace The **"Setting Up Your Workspace"** screen displays a loading spinner while the system automatically prepares your environment. Once complete, you receive a **Gateway Token** and the **OpenClaw web admin URL** to log in and start using immediately. @@ -101,7 +101,7 @@ Each instance in the list shows: instance name, status, AI model in use, version 1. In My Agents, find the instance you want to access. 2. Click **"Open"** on the instance. -3. You are redirected straight to the OpenClaw web admin — no wizard or re-provisioning required. +3. You are redirected straight to the OpenClaw web admin — no wizard or re-provisioning required. ### Stop an Instance diff --git a/English/ai-stack/agent-base/agent-runtime/runtime-reference.md b/English/ai-stack/agent-base/agent-runtime/runtime-reference.md index 1a4bfbd4f..7caede270 100644 --- a/English/ai-stack/agent-base/agent-runtime/runtime-reference.md +++ b/English/ai-stack/agent-base/agent-runtime/runtime-reference.md @@ -1,6 +1,6 @@ # Runtime Reference -> The Runtime manages the full lifecycle of your agent's compute environment — container deployment, autoscaling, versioning, and endpoints. +> The Runtime manages the full lifecycle of your agent's compute environment — container deployment, autoscaling, versioning, and endpoints. *** @@ -22,11 +22,11 @@ A **Runtime** is the managed compute environment that runs your containerized ag ### Versions -Every time you deploy a new container image to a runtime, AgentBase creates a new **Version**. Versions are immutable — a version's image and configuration never change after creation. +Every time you deploy a new container image to a runtime, AgentBase creates a new **Version**. Versions are immutable — a version's image and configuration never change after creation. ### Endpoint -An **Endpoint** is the URL that clients call to interact with your agent. A runtime can have multiple endpoints and multiple versions — these are independent concepts. The **default** endpoint automatically tracks the latest version whenever a new version is deployed. You can designate any endpoint as the default, and create additional endpoints pinned to specific versions (for example, for canary or staging traffic). +An **Endpoint** is the URL that clients call to interact with your agent. A runtime can have multiple endpoints and multiple versions — these are independent concepts. The **default** endpoint automatically tracks the latest version whenever a new version is deployed. You can designate any endpoint as the default, and create additional endpoints pinned to specific versions (for example, for canary or staging traffic). ### Compute Flavors @@ -36,24 +36,24 @@ A **Compute Flavor** defines the CPU and RAM allocated to each replica of your a The Runtime Service supports autoscaling based on CPU or RAM utilization. You define: -* `minReplicas`: The floor — always running (range: 1–10) -* `maxReplicas`: The ceiling — caps resource usage (range: 1–10) -* `cpuUtilization` and `memoryUtilization`: Thresholds (25–75%) that trigger scale-out +* `minReplicas`: The floor — always running (range: 1–10) +* `maxReplicas`: The ceiling — caps resource usage (range: 1–10) +* `cpuUtilization` and `memoryUtilization`: Thresholds (25–75%) that trigger scale-out When load drops, AgentBase scales replicas back down to `minReplicas`. ### Security Settings -* **IP Access Control** — restricts which source IP CIDR ranges can reach the Runtime endpoint; leave empty to allow all sources. -* **Inbound Identity** — configures how incoming requests are authenticated, via an **Inbound Auth type**: **IAM Permissions** (GreenNode AI Platform IAM token), **JSON Web Tokens (JWT)** (validated via a Discovery URL or inline JWKS), or **No authorization** (publicly accessible, no access control). +* **IP Access Control** — restricts which source IP CIDR ranges can reach the Runtime endpoint; leave empty to allow all sources. +* **Inbound Identity** — configures how incoming requests are authenticated, via an **Inbound Auth type**: **IAM Permissions** (GreenNode AI Platform IAM token), **JSON Web Tokens (JWT)** (validated via a Discovery URL or inline JWKS), or **No authorization** (publicly accessible, no access control). ### Service Contract Your agent container must satisfy these requirements to work correctly with the Runtime Service: -1. **Listen on port 8080** — the required port; `app.run(host="0.0.0.0", port=8080)` +1. **Listen on port 8080** — the required port; `app.run(host="0.0.0.0", port=8080)` 2. **Health check endpoint**: `GET /health` must return HTTP 200 to pass readiness checks -3. **Stateless**: Do not store session state in process memory — use the Memory Service instead +3. **Stateless**: Do not store session state in process memory — use the Memory Service instead **Auto-injected environment variables** (available in all deployed agent containers): @@ -71,24 +71,24 @@ Your agent container must satisfy these requirements to work correctly with the ``` Runtime: my-order-agent -│ -├── Versions -│ ├── Version 1 (image: my-agent:v1.0.0) -│ └── Version 2 (image: my-agent:v2.0.0) ← latest -│ -├── Endpoints -│ ├── DEFAULT → https:// (auto-tracks latest version) -│ └── canary → https:// (pinned to Version 1) -│ -└── Autoscaling: min=1, max=3, CPU threshold=50% +│ +├── Versions +│ ├── Version 1 (image: my-agent:v1.0.0) +│ └── Version 2 (image: my-agent:v2.0.0) ← latest +│ +├── Endpoints +│ ├── DEFAULT → https:// (auto-tracks latest version) +│ └── canary → https:// (pinned to Version 1) +│ +└── Autoscaling: min=1, max=3, CPU threshold=50% ``` **Key facts:** -* Each `PATCH /agent-runtimes/{id}` creates a new **version** — versions and endpoints are independent concepts under a runtime +* Each `PATCH /agent-runtimes/{id}` creates a new **version** — versions and endpoints are independent concepts under a runtime * The **default** endpoint automatically tracks the latest version whenever a new version is deployed -* A runtime can have multiple endpoints — you choose which one is the default -* You have full control over all endpoints — create, update, or delete +* A runtime can have multiple endpoints — you choose which one is the default +* You have full control over all endpoints — create, update, or delete *** @@ -108,16 +108,16 @@ Runtime: my-order-agent | **Description** | `Production order agent` | Optional | | **Image URL** | `vcr.vngcloud.vn//my-agent:v1` | Full image path including tag | | **Flavor** | `1x1-general` | 1 CPU, 1 GB RAM | -| **Min Replicas** | `1` | Range: 1–10 | +| **Min Replicas** | `1` | Range: 1–10 | | **Max Replicas** | `1` | Set >1 to enable autoscaling | -| **CPU Threshold** | `50` | Scale out when CPU exceeds this % (25–75) | -| **Memory Threshold** | `50` | Scale out when RAM exceeds this % (25–75) | -| **Registry Auth** | Enable if private | Username = robot account `backendName` (see [Supporting Services — Robot Accounts](../supporting-services.md#create-a-robot-account)) | +| **CPU Threshold** | `50` | Scale out when CPU exceeds this % (25–75) | +| **Memory Threshold** | `50` | Scale out when RAM exceeds this % (25–75) | +| **Registry Auth** | Enable if private | Username = robot account `backendName` (see [Supporting Services — Robot Accounts](../supporting-services.md#create-a-robot-account)) | | **Environment Variables** | `KEY=value` | Non-sensitive config only | -| **IP Access Control** | `10.0.0.0/16` | Optional — allowed source IP CIDR ranges; leave empty to allow all sources | -| **Inbound Auth type** | `JSON Web Tokens (JWT)` | Optional — **IAM Permissions**, **JWT** (Discovery URL or inline JWKS), or **No authorization** | +| **IP Access Control** | `10.0.0.0/16` | Optional — allowed source IP CIDR ranges; leave empty to allow all sources | +| **Inbound Auth type** | `JSON Web Tokens (JWT)` | Optional — **IAM Permissions**, **JWT** (Discovery URL or inline JWKS), or **No authorization** | -![Security Settings — IP Access Control and Inbound Identity](<../../../.gitbook/assets/Agentbase-image/Security-Runtime.png>) +![Security Settings — IP Access Control and Inbound Identity](<../../../.gitbook/assets/Agentbase-image/Security-Runtime.png>) 5. Click **Create** 6. Runtime appears with status `CREATING`, then transitions to `ACTIVE` @@ -147,7 +147,7 @@ In Runtime detail page, find the runtime → **Delete** → confirm ### RESTful API -> **Prerequisite:** All API examples below use `$TOKEN` — an IAM bearer token. See [Configure Authentication](../getting-started.md#configure-authentication) for how to obtain it. +> **Prerequisite:** All API examples below use `$TOKEN` — an IAM bearer token. See [Configure Authentication](../getting-started.md#configure-authentication) for how to obtain it. #### Create a Runtime @@ -400,7 +400,7 @@ Your agent container must fulfill these requirements: | Requirement | Value | Notes | | ----------------- | ------------- | ----------------------------- | -| Listen port | `8080` | Required — not configurable | +| Listen port | `8080` | Required — not configurable | | Health check path | `GET /health` | Must return HTTP 200 | **Using the greennode-agentbase SDK (recommended):** @@ -454,6 +454,6 @@ Incoming requests to your agent include: | `X-GreenNode-AgentBase-User-Id` | End-user ID (use as `actorId` for memory operations) | | `X-GreenNode-AgentBase-Session-Id` | Session ID (use as `thread_id` for LangGraph checkpointing) | -> **Important:** If your agent uses memory, validate that these headers are present and return an error if missing. Do not fall back to default values — silent defaults cause data mixing between users. +> **Important:** If your agent uses memory, validate that these headers are present and return an error if missing. Do not fall back to default values — silent defaults cause data mixing between users. *** diff --git a/English/ai-stack/agent-base/memory/README.md b/English/ai-stack/agent-base/memory/README.md index 8165ee3a2..0b2dada8c 100644 --- a/English/ai-stack/agent-base/memory/README.md +++ b/English/ai-stack/agent-base/memory/README.md @@ -1,12 +1,12 @@ # Memory -> The Memory service gives agents the ability to remember — across turns in a conversation (short-term via events) and across sessions and time (long-term via memory records with semantic search). +> The Memory service gives agents the ability to remember — across turns in a conversation (short-term via events) and across sessions and time (long-term via memory records with semantic search). *** ## Core Concepts -LLMs are stateless by nature — each API call is independent. For an agent to maintain context across a conversation or across sessions, it needs an external memory store. AgentBase's Memory module provides this as a managed service with two memory layers: +LLMs are stateless by nature — each API call is independent. For an agent to maintain context across a conversation or across sessions, it needs an external memory store. AgentBase's Memory module provides this as a managed service with two memory layers: ### Short-Term Memory (Conversation History) @@ -14,12 +14,12 @@ Short-term memory stores the **ordered sequence of messages** in a conversation ``` Session 1: user 1 -───────────────────────────────────────────────────────── +───────────────────────────────────────────────────────── Role Content human "What's the weather like in Hanoi today?" -assistant "Currently 28°C, partly cloudy in Hanoi." +assistant "Currently 28°C, partly cloudy in Hanoi." human "What about tomorrow?" -assistant "Tomorrow: 31°C, sunny with light winds." +assistant "Tomorrow: 31°C, sunny with light winds." ``` **Key characteristics:** @@ -31,11 +31,11 @@ assistant "Tomorrow: 31°C, sunny with light winds." ### Long-Term Memory (Semantic Facts) -Long-term memory stores **persistent facts about entities** — users, products, preferences, past interactions — and retrieves them via **semantic similarity search** against the current query. +Long-term memory stores **persistent facts about entities** — users, products, preferences, past interactions — and retrieves them via **semantic similarity search** against the current query. ``` User ID - Namespace -─────────────────────────────────────────────────────────────────────── +─────────────────────────────────────────────────────────────────────── fact_001 "User prefers delivery to home address" fact_002 "User has a premium subscription" fact_003 "User frequently orders electronics" @@ -66,7 +66,7 @@ Facts are extracted from conversation events using a **Long-Term Memory Strategy | ------------------------------------ | ------------------------------------------------------------------ | ---------------------------------------- | | **Memory** | Top-level container (memory store) holding events and records | Permanent until deleted | | **Event** | Single conversation turn (role + message) | Expires after `eventExpiryDuration` days | -| **Actor** | Participant identifier — represents the end-user (not the agent) | Created on first event | +| **Actor** | Participant identifier — represents the end-user (not the agent) | Created on first event | | **Session** | Conversation thread within an actor | Created on first event | | **Memory Record** | Distilled long-term fact extracted from events | Permanent until deleted | | **Long-Term Memory Strategy (LTMS)** | Extraction rules for generating memory records | Configured at memory creation | @@ -81,9 +81,9 @@ Available variables: `{memoryStrategyId}`, `{actorId}`, `{sessionId}` *** -## Setup — Create Memory Store +## Setup — Create Memory Store -Before using short-term or long-term memory, you must create a **Memory store** — the top-level container that holds all events and memory records for your agent. +Before using short-term or long-term memory, you must create a **Memory store** — the top-level container that holds all events and memory records for your agent. ### Portal @@ -92,10 +92,10 @@ Before using short-term or long-term memory, you must create a **Memory store** 1. Open https://aiplatform.console.greennode.ai/memory 2. Click **"Create Memory"** 3. Fill in: - * **Name**: e.g., `customer-support-memory` (0–50 chars, `^[a-zA-Z0-9._-]*$`) + * **Name**: e.g., `customer-support-memory` (0–50 chars, `^[a-zA-Z0-9._-]*$`) * **Description**: optional 4. Configure **Short-Term Memory**: - * **Event Expiry Duration**: number of days before conversation events are automatically deleted (1–365), e.g., `30` days + * **Event Expiry Duration**: number of days before conversation events are automatically deleted (1–365), e.g., `30` days 5. Add one or more **Long-Term Memory Strategies** (optional, for long-term memory): * **Strategy Name**: e.g., `semantic-facts` * **Type**: `SEMANTIC`, `USER_PREFERENCE`, or `CUSTOM` @@ -129,7 +129,7 @@ From the memory list page → click a memory name ### RESTful API -> **Prerequisite:** All API examples below use `$TOKEN` — an IAM bearer token. See [Configure Authentication](../getting-started.md#configure-authentication) for how to obtain it. +> **Prerequisite:** All API examples below use `$TOKEN` — an IAM bearer token. See [Configure Authentication](../getting-started.md#configure-authentication) for how to obtain it. #### Create a Memory Store @@ -276,7 +276,7 @@ memory, strategies = asyncio.run(asyncio.gather( print(f"Name: {memory.name}, Status: {memory.status}") for s in strategies: - print(f" {s.get('name')} — Type: {s['type']}") + print(f" {s.get('name')} — Type: {s['type']}") ``` #### Delete a Memory Store @@ -287,16 +287,16 @@ asyncio.run(client.delete_async(id=MEMORY_ID)) *** -## Step 2 — Use Memory in Your Agent +## Step 2 — Use Memory in Your Agent Once your Memory Store is created, your agent reads and writes memory at runtime. Choose the approach that fits your stack. | Approach | When to use | | ---------------------------- | ------------------------------------------------------------------------------------------------------- | -| **A: Agentic Frameworks** | Building with LangGraph or LangChain — use built-in checkpointer for short-term + tools for long-term | +| **A: Agentic Frameworks** | Building with LangGraph or LangChain — use built-in checkpointer for short-term + tools for long-term | | **B: Direct SDK / REST API** | Any other stack, or when you need full control over when and how memory is read and written | -> **Required headers:** Your agent receives `X-GreenNode-AgentBase-User-Id` (maps to `actor_id`) and `X-GreenNode-AgentBase-Session-Id` (maps to `thread_id` / `session_id`) on every request from the Runtime. Always validate them before performing memory operations — never fall back to defaults, as silent defaults cause data mixing between users. +> **Required headers:** Your agent receives `X-GreenNode-AgentBase-User-Id` (maps to `actor_id`) and `X-GreenNode-AgentBase-Session-Id` (maps to `thread_id` / `session_id`) on every request from the Runtime. Always validate them before performing memory operations — never fall back to defaults, as silent defaults cause data mixing between users. ```python @app.entrypoint @@ -317,7 +317,7 @@ def handler(payload: dict, context: RequestContext) -> dict: pip install "greennode-agent-bridge[langgraph]" ``` -#### Short-Term Memory — LangGraph Checkpointer +#### Short-Term Memory — LangGraph Checkpointer Pass `AgentBaseMemoryEvents` as the checkpointer when compiling your graph. LangGraph automatically writes and loads conversation history using the `thread_id` (mapped from `session_id`). @@ -339,9 +339,9 @@ result = graph.invoke( ) ``` -#### Long-Term Memory — Tool-Based Approach +#### Long-Term Memory — Tool-Based Approach -Define `remember` and `recall` as agent tools backed by `MemoryClient`. The `actor_id` and `strategy_id` are resolved from runtime config — they must **not** be exposed as LLM-accessible parameters. +Define `remember` and `recall` as agent tools backed by `MemoryClient`. The `actor_id` and `strategy_id` are resolved from runtime config — they must **not** be exposed as LLM-accessible parameters. ```python from greennode_agentbase.memory import MemoryClient @@ -541,7 +541,7 @@ for record in results: ## Reference: Browse and Manage Memory Data -Use these operations to inspect memory data — useful for debugging, auditing, or building admin tooling. +Use these operations to inspect memory data — useful for debugging, auditing, or building admin tooling. ### List Actors @@ -565,10 +565,10 @@ curl -s "https://agentbase.api.vngcloud.vn/memory/memories/$MEMORY_ID/memory-rec | Parameter | Value | Notes | | -------------------------------- | ------------ | ------------------------------- | -| `eventExpiryDuration` range | 1–365 days | Set at memory store creation | +| `eventExpiryDuration` range | 1–365 days | Set at memory store creation | | Memory name max length | 50 chars | Pattern:`^[a-zA-Z0-9._-]*$` | -| Semantic search `limit` range | 5–200 | Per search request | -| Semantic search `scoreThreshold` | 0–1 float | Higher = more strict similarity | +| Semantic search `limit` range | 5–200 | Per search request | +| Semantic search `scoreThreshold` | 0–1 float | Higher = more strict similarity | | Max `from` for event pagination | 5000 | Offset-based | *** @@ -579,7 +579,7 @@ curl -s "https://agentbase.api.vngcloud.vn/memory/memories/$MEMORY_ID/memory-rec | --------------------------- | ------------------------------------- | ------------------------------------------------------ | | 401 Unauthorized | Expired IAM token | Re-obtain token | | Memory not found | Wrong memory ID | Verify with `GET /memories` list | -| No records returned | Namespace mismatch or async delay | Records generated asynchronously — wait and retry | +| No records returned | Namespace mismatch or async delay | Records generated asynchronously — wait and retry | | Events not appearing | Events expired | Check `eventExpiryDuration` | | Auto-generation not working | Strategy misconfigured | Verify `enableAutomaticMemoryRecordGeneration: true` | | "Missing required headers" | Request missing User-Id or Session-Id | Include both headers in every request that uses memory | diff --git a/English/ai-stack/ai-gateway/README.md b/English/ai-stack/ai-gateway/README.md index 68642669d..e73ef916c 100644 --- a/English/ai-stack/ai-gateway/README.md +++ b/English/ai-stack/ai-gateway/README.md @@ -1,2 +1,33 @@ +--- +description: An intelligent connection gateway for AI services +--- + # AI Gateway +**AI Gateway** is a centralized gateway that lets you integrate AI models from multiple providers (OpenAI, Google, Deepseek, and more) through a single endpoint — reducing the complexity of switching models, centralizing monitoring, optimizing cost, and protecting your data. + +*** + +## Overview + +| Capability | Description | +|---|---| +| **Multi-LLM support** | Flexibly integrate multiple LLMs from multiple providers through one gateway | +| **Monitoring** | Track performance and activity through metrics and logs, including detailed latency breakdowns | +| **Access control** | Manage **Authentication Tokens** and set rate limits by request count or token count | +| **Cost optimization** | Caching reduces the number of requests sent to the model, saving cost and improving response time | + +*** + +## Getting Started + +| I want to... | Go to | +|---|---| +| Understand what AI Gateway is and what it solves | [What is AI Gateway?](what-is-ai-gateway.md) | +| Initialize a gateway, send my first request, and monitor activity | [Get Started with AI Gateway](get-starting-with-ai-gateway/README.md) | +| Add, edit, or remove providers and models on the gateway | [Working with Providers and Models](ai-gateway/working-with-providers-and-models/README.md) | +| Create and manage Authentication Tokens | [Working with Authentication Tokens](ai-gateway/working-with-authentication-tokens.md) | +| Reduce cost and latency with caching | [Caching](ai-gateway/caching.md) | +| Limit requests or tokens within a time window | [Rate Limit](ai-gateway/rate-limit.md) | +| Learn how AI Gateway protects sensitive information | [Security](security.md) | +| See the pricing policy for the service | [Pricing](pricing.md) | diff --git a/English/ai-stack/ai-gateway/ai-gateway/rate-limit.md b/English/ai-stack/ai-gateway/ai-gateway/rate-limit.md index 07722d952..b4577785b 100644 --- a/English/ai-stack/ai-gateway/ai-gateway/rate-limit.md +++ b/English/ai-stack/ai-gateway/ai-gateway/rate-limit.md @@ -2,7 +2,8 @@ description: >- Rate Limit is a mechanism used to control the number of requests or tokens within a specified period of time. It helps protect the system from abuse, - ensures fairness when multiple users share the + ensures fairness when multiple users share the same gateway, and optimizes + cost and stability for the model --- # Rate Limit @@ -40,6 +41,6 @@ description: >- * 1 Month * **Window Time Type:** Currently supports **Fixed Window** only. -### 3 Nhấn **Lưu** cấu hình. +### 3. Save the Configuration
diff --git a/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/README.md b/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/README.md index d098963c8..c5c1cbab4 100644 --- a/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/README.md +++ b/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/README.md @@ -1,2 +1,3 @@ -# Get starting with AI Gateway +# Get Started with AI Gateway +You can use the following guides to get started with AI Gateway. If you run into any issue while using the service, please contact GreenNode at [**support@greennode.ai**](mailto:support@greennode.ai) or via hotline **19001549**. diff --git a/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/initialize-ai-gateway.md b/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/initialize-ai-gateway.md deleted file mode 100644 index ad5aa93fb..000000000 --- a/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/initialize-ai-gateway.md +++ /dev/null @@ -1,22 +0,0 @@ -# Initialize AI Gateway - -To start using AI Gateway on GreenNode, follow these steps: - -**Step 1:** Access the AI Gateway interface on the GreenNode Console via: [http://aigateway.console.greennode.ai/](http://aigateway.console.greennode.ai/)​ - -**Step 2:** In the left-hand menu, select AI Gateway, then click the Create an AI Gateway button. - -
- -**Step 3:** On the Create New Gateway screen, fill in the following information: - -* **AI Gateway Name:** Provide a memorable name for your gateway. The name must contain only a–z, A–Z, 0–9, underscore (\_) or hyphen (-), and be between 5 and 50 characters -* **Model Provider:** - * Select the AI model provider you want to connect to, such as OpenAI, Anthropic, Google, or DeepSeek. - * **API Key:** Enter the corresponding API Key from the provider. If you do not have one, click Get API Key — you will be redirected to the provider’s page to obtain it. - * **Choose Model:** Select the AI model you want to use (e.g., gemini-1.5, gemini-2.0, etc.). To view the full list, click View full list to display all supported models. -* **Gateway Config:** By default, the system enables the Authenticated Gateway feature. An authentication token will be automatically generated — you can use this token to send requests to the AI Gateway - -**Step 4:** Click Create an AI Gateway. Your AI Gateway will be initialized and ready for use. - -
diff --git a/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/monitoring-ai-gateway-activity.md b/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/monitoring-ai-gateway-activity.md deleted file mode 100644 index 3a4242ce2..000000000 --- a/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/monitoring-ai-gateway-activity.md +++ /dev/null @@ -1,41 +0,0 @@ -# Monitoring AI Gateway Activity - -To track and analyze the operation of an active AI Gateway, you can monitor it through the following: - -## Metric - -In the detailed view of a Gateway, select the Monitor tab to observe real-time metrics displayed in charts, including: - -* **Requests**: Total number of requests sent to the AI Gateway. -* **Errors**: Number of requests sent to the AI Gateway that resulted in errors -* **Tokens**: Total number of tokens used, including: - * `input`: input tokens (your prompt/question). - * `output`: output tokens (responses from the LLM model). - -You can customize the observation time range (15m, 30m, 1h, 2h, etc.) and filter by specific Provider or Model. - -
- -## Logs - -In the detailed view of a Gateway, select the Log tab to view a list of all requests sent through the Gateway. - -Here, you can see request details including: - -* **Time:** Timestamp of the request. -* **Status:** Request status, including Success, Error, or Timeout. -* **Model:** Name of the model used. -* **Tokens:** Number of input/output tokens. -* **Duration:** Total processing time of the request. - -You can customize the observation time range (24h, 1d, 2d, etc.) and filter by specific Status. - -
- -Additionally, you can view detailed information for a specific request by: - -* Clicking the Detail icon in the Action column to open the Detail Log. -* Here you will find: - * **Input**: The original prompt or question sent. - * **Output**: The response returned from the LLM model. - * **Thông tin bổ sung**: host, model, response time, and more. diff --git a/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/sending-requests-to-ai-gateway.md b/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/sending-requests-to-ai-gateway.md deleted file mode 100644 index 8aed13e18..000000000 --- a/English/ai-stack/ai-gateway/get-starting-with-ai-gateway/sending-requests-to-ai-gateway.md +++ /dev/null @@ -1,50 +0,0 @@ -# Sending Requests to AI Gateway - -After successfully creating an AI Gateway, you can start sending requests to the configured AI model by following these steps: - -**Step 1:** Access the [AI Gateway Portal](http://aigateway.console.greennode.ai/) and locate the gateway you just created. - -**Step 2:** In the Providers & Model section, find the AI model you configured. Click the Curl command icon to get a sample request. - -
- -**Step 3:** Copy the displayed curl command and execute it on your local machine (via Terminal or Command Prompt). - -
- -Example: - -```bash -curl -X POST https://user-60108-gateway-0b50037b-93.ai-gateway.vngcloud.vn/deepseek/deepseek-chat/chat/completions \ - --header 'Authorization: Bearer {AUTHENTICATION_TOKEN}' \ - --header 'Content-Type: application/json' \ - --data '{ - "model": "deepseek-chat", - "messages": [ - { - "role": "user", - "content": "What is AI?" - } - ] - }' -``` - -**Note:** - -* Replace `{AUTHENTICATION_TOKEN}` with the token provided after creating the Gateway -* You can modify the prompt content (the question in the "content" field) to suit your use case. -* If your AI Gateway is using Authenticated Gateway mode, you must include a header named cf-aig-authorization in your HTTP request. - -For example, instead of using: - -```http -Authorization: Bearer {AUTHENTICATION_TOKEN} -``` - -You must use: - -```http -cf-aig-authorization: Bearer {AUTHENTICATION_TOKEN} -``` - -After sending the request, you will receive a response from the AI model in JSON format. diff --git a/English/ai-stack/ai-gateway/pricing.md b/English/ai-stack/ai-gateway/pricing.md index d51602834..4aabcce69 100644 --- a/English/ai-stack/ai-gateway/pricing.md +++ b/English/ai-stack/ai-gateway/pricing.md @@ -1,6 +1,6 @@ # Pricing -Currently, AI Gateway on GreenNode is provided free of charge for customers to փորձ and evaluate. If you would like to try the product, please: +Currently, AI Gateway on GreenNode is provided free of charge for customers to try and evaluate. If you would like to try the product, please: Send an email to support@greennode.ai diff --git a/English/ai-stack/ai-infrastructure.md b/English/ai-stack/ai-infrastructure.md index 7d378e7f3..1dbc75940 100644 --- a/English/ai-stack/ai-infrastructure.md +++ b/English/ai-stack/ai-infrastructure.md @@ -1,2 +1,7 @@ # AI Infrastructure +**AI Infrastructure** in the AI Stack is the layer that provides the hardware, software, and systems required to operate, train, and deploy AI models. Its main responsibility is to supply compute (CPU/GPU), volume, network, security, and orchestration for every AI workload. + +The main components of AI Infrastructure are: + +
ComponentDescription
VKSOrchestration for every AI workload (training, inference, pipeline, autoscaling)

OpenSearch Cluster Database

PostgreSQL Database

Vector database used for semantic search, RAG, embedding storage, AI metadata, and more
Object StorageStores training data, model repository, and more

NVIDIA GPU

High Performance Compute

Network

GPU infrastructure for AI training/inference: HGX H100, L40s, A40, and more

Powerful compute platform with Intel Gen4 and AMD Genoa

High-performance interconnect: InfiniBand, 100G / 50G Ethernet

diff --git a/English/ai-stack/ai-platform/model-registry/import-model-registry-using-a-custom-container.md b/English/ai-stack/ai-platform/model-registry/import-model-registry-using-a-custom-container.md index 1429d74ff..804e24201 100644 --- a/English/ai-stack/ai-platform/model-registry/import-model-registry-using-a-custom-container.md +++ b/English/ai-stack/ai-platform/model-registry/import-model-registry-using-a-custom-container.md @@ -7,7 +7,7 @@ ## Step 2: Import Model Registry -* **Region & Model registry name**: Select the region and provide a specific name for your model.n. +* **Region & Model registry name**: Select the region and provide a specific name for your model. * Select “Custom container” in the Container section. * **Custom image URI**: * Provide the URL of your custom container image, stored in a container registry.\ diff --git a/English/ai-stack/ai-platform/model-registry/import-model-registry-using-vllm.md b/English/ai-stack/ai-platform/model-registry/import-model-registry-using-vllm.md index bf69c799e..6db850195 100644 --- a/English/ai-stack/ai-platform/model-registry/import-model-registry-using-vllm.md +++ b/English/ai-stack/ai-platform/model-registry/import-model-registry-using-vllm.md @@ -3,7 +3,7 @@ ## Step 1: Access Model Registry * Log in with your GreenNode account and navigate to the [Model Registry Dashboard](https://aiplatform.console.greennode.ai/registry). -* Find and click the "Import a model registry" button.. +* Find and click the "Import a model registry" button. ## Step 2: Configure Model Registry @@ -33,7 +33,7 @@ ... ... ``` -* **Cấu hình vLLM (vLLM Settings):** +* **vLLM Settings:** * **Served model name:** The model name used in the API.\ Note: This name will also be used in the `model_name` tag * **Max number of sequences:** Maximum number of sequences per iteration. Default: 256. diff --git a/English/ai-stack/model-as-a-service/maas-api.md b/English/ai-stack/model-as-a-service/maas-api.md index 7e3fa2811..44ebaf8a6 100644 --- a/English/ai-stack/model-as-a-service/maas-api.md +++ b/English/ai-stack/model-as-a-service/maas-api.md @@ -1,8 +1,8 @@ # MaaS API -**MaaS** cung cấp một API **tương thích với OpenAI** để thực hiện suy luận mô hình một cách liền mạch. Bạn có thể dễ dàng tích hợp bằng **Python, JavaScript SDK**, hoặc trực tiếp qua **terminal với cURL**. +**MaaS** provides an **OpenAI-compatible** API for seamless model inference. You can integrate easily using the **Python or JavaScript SDK**, or directly from your **terminal with cURL**. -Tham khảo các Script trong API Usage trên Portal +Refer to the scripts under API Usage on the Portal. _Curl_ diff --git a/Vietnamese/SUMMARY.md b/Vietnamese/SUMMARY.md index 3aa2452f1..5fd972d41 100644 --- a/Vietnamese/SUMMARY.md +++ b/Vietnamese/SUMMARY.md @@ -841,20 +841,14 @@ * [AI Gateway](ai-stack/ai-gateway/README.md) * [AI Gateway là gì?](ai-stack/ai-gateway/ai-gateway-la-gi.md) * [Bắt đầu với AI Gateway](ai-stack/ai-gateway/bat-dau-voi-ai-gateway.md) - * [Khởi tạo AI Gateway](ai-stack/ai-gateway/bat-dau-voi-ai-gateway/khoi-tao-ai-gateway.md) - * [Gọi request tới AI Gateway](ai-stack/ai-gateway/bat-dau-voi-ai-gateway/goi-request-toi-ai-gateway.md) - * [Giám sát hoạt động của AI Gateway](ai-stack/ai-gateway/bat-dau-voi-ai-gateway/giam-sat-hoat-dong-cua-ai-gateway.md) - * [AI Gateway](ai-stack/ai-gateway/ai-gateway/README.md) * [Khởi tạo AI Gateway](ai-stack/ai-gateway/ai-gateway/khoi-tao-ai-gateway.md) - * [Làm việc với Provider và Model](ai-stack/ai-gateway/ai-gateway/lam-viec-voi-provider-va-model/README.md) - * [Model Providers](ai-stack/ai-gateway/model-providers.md) - * [Seft-host Models](ai-stack/ai-gateway/ai-gateway/lam-viec-voi-provider-va-model/seft-host-models.md) * [Gọi request tới AI Gateway](ai-stack/ai-gateway/ai-gateway/goi-request-toi-ai-gateway.md) - * [Làm việc với Authentication Token](ai-stack/ai-gateway/ai-gateway/lam-viec-voi-authentication-token.md) - * [Caching](ai-stack/ai-gateway/ai-gateway/caching-coming-soon.md) - * [Guardrails (Coming soon)](ai-stack/ai-gateway/ai-gateway/guardrails-coming-soon.md) - * [Giới Hạn rate](ai-stack/ai-gateway/ai-gateway/rate-limit-coming-soon.md) - * [Giám sát hoạt động](ai-stack/ai-gateway/giam-sat-hoat-dong.md) + * [Giám sát hoạt động](ai-stack/ai-gateway/giam-sat-hoat-dong.md) + * [Làm việc với Provider và Model](ai-stack/ai-gateway/ai-gateway/lam-viec-voi-provider-va-model/README.md) + * [Model Providers](ai-stack/ai-gateway/model-providers.md) + * [Làm việc với Authentication Token](ai-stack/ai-gateway/ai-gateway/lam-viec-voi-authentication-token.md) + * [Caching](ai-stack/ai-gateway/ai-gateway/caching-coming-soon.md) + * [Giới hạn Rate](ai-stack/ai-gateway/ai-gateway/rate-limit-coming-soon.md) * [Bảo mật](ai-stack/ai-gateway/bao-mat.md) * [Cách tính giá](ai-stack/ai-gateway/cach-tinh-gia.md) * [Token Plan](ai-stack/token-plan/README.md) @@ -871,7 +865,6 @@ * [OpenCode](ai-stack/ai-coding/dong-lenh/opencode.md) * [Có giao diện (GUI)](ai-stack/ai-coding/co-giao-dien/README.md) * [Codex Desktop](ai-stack/ai-coding/co-giao-dien/codex-desktop.md) - * [GenAI Studio](ai-stack/genai-studio.md) * [GreenNode AgentBase](ai-stack/agent-base/README.md) * [Bắt đầu](ai-stack/agent-base/getting-started.md) * [Sử dụng GreenNode CLI để quản lý AgentBase](ai-stack/agent-base/su-dung-greennode-cli-de-quan-ly-agentbase.md) diff --git a/Vietnamese/ai-stack/agent-base/agent-runtime/openclaw/PRD-openclaw-one-click-agentbase.md b/Vietnamese/ai-stack/agent-base/agent-runtime/openclaw/PRD-openclaw-one-click-agentbase.md deleted file mode 100644 index c4c7a5855..000000000 --- a/Vietnamese/ai-stack/agent-base/agent-runtime/openclaw/PRD-openclaw-one-click-agentbase.md +++ /dev/null @@ -1,788 +0,0 @@ -# PRD: 1-Click Deploy OpenClaw trên GreenNode AgentBase - -## Document Information - -| Field | Value | -| ------------ | ------------------------------------------- | -| Product | GreenNode AgentBase | -| Feature | 1-Click Deploy OpenClaw — Community Edition | -| Version | 1.3 | -| Created Date | 2026-03-25 | -| Updated Date | 2026-03-30 | -| Author | Product Team — AgentBase | -| Status | In Review | - -*** - -## 1. Overview - -### 1.1 Background - -[OpenClaw](https://open.claw.cloud/) là một open-source AI agent chạy trên máy tính cá nhân, có thể tự động hoàn thành các tác vụ: duyệt web, quản lý file, chạy lệnh, viết code, tích hợp messaging. - -**Vấn đề/Pain points:** - -* Developer muốn thử OpenClaw phải tự cài đặt, cấu hình API key, chọn model thủ công — mất 30–60 phút setup -* End-user (non-developer) hoàn toàn không thể tiếp cận OpenClaw vì quá nhiều bước kỹ thuật -* GreenNode MaaS chưa có "entry point" thân thiện để giới thiệu đến cộng đồng rộng hơn - -**Sự khác biệt chính:** - -* **Giải pháp hiện tại** : Tự cài OpenClaw trên máy local, tự nhập API key, tự cấu hình — 30–60 phút, cần kiến thức DevOps -* **Giải pháp mới** : 1-Click Deploy từ Agent Marketplace trên AgentBase — best case 40–60 giây, không cần kiến thức kỹ thuật, tự động kết nối GreenNode MaaS - -### 1.2 Objective - -Cung cấp khả năng spin up một instance OpenClaw cá nhân từ Agent Marketplace trong 40–60 giây (best case), cho phép người dùng: - -* Bất kỳ ai vào web AgentBase đều có thể dùng OpenClaw không cần kiến thức kỹ thuật -* User có tài khoản VNG được tự động kết nối GreenNode MaaS — không cần copy/paste API key -* User không có tài khoản VNG vẫn có thể dùng bằng cách mang API key của bên thứ 3 (BYOK) -* Sau khi deploy, user truy cập thẳng vào portal OpenClaw Gateway để dùng ngay -* User có thể cấu hình Channel (Telegram bot) ngay từ bước thiết lập - -### 1.3 Scope - -PRD này bao gồm các thay đổi UI/UX cho: - -1. Agent Marketplace — OpenClaw featured card và hero banner -2. Màn hình cấu hình Deploy (Screen 3) — AI source, tên instance, flavor, channel -3. Màn hình Provisioning (Screen 5) — "Setting Up Your Workspace" -4. Màn hình Deploy Success (Screen 6) — thông tin instance và gateway password -5. OpenClaw Gateway Dashboard (Screen 7) — portal chat -6. My Agents Dashboard (Screen 8) — quản lý instance - -**Ngoài phạm vi (Out of Scope):** - -* Billing / usage metering cho từng instance -* Multi-instance per user (giai đoạn 1: 1 instance/user) -* Custom domain cho instance OpenClaw -* Persistent storage / backup dữ liệu OpenClaw -* Team/shared instance - -### 1.4 Workflow Overview - -| Component | Integration | Description | -| ------------------ | -------------------------- | ----------------------------------------------------- | -| AgentBase Frontend | GreenNode Portal Auth | Dùng session login sẵn có, không cần auth popup riêng | -| AgentBase Backend | GreenNode MaaS (AIP) | Internal API bridge tự động provision MaaS key | -| AgentBase Backend | AgentBase Identity Service | Tạo Identity cho mỗi OpenClaw instance | -| AgentBase Backend | AgentBase Runtime Service | Deploy container OpenClaw với env vars được inject | -| AgentBase Frontend | Telegram Bot API | Cấu hình Channel bot token (optional) | - -### 1.5 Key Features Summary - -| Feature | Description | Phase | -| --------------------- | ----------------------------------------------------------- | ------- | -| Agent Marketplace | OpenClaw featured card + hero CTA "Deploy 1-Click" | MVP | -| 1-Click Deploy — MaaS | Tự động kết nối GreenNode MaaS, không cần nhập key | MVP | -| 1-Click Deploy — BYOK | Mang API key từ provider bên ngoài (OpenAI, Anthropic...) | MVP | -| Channel Configuration | Cấu hình Telegram bot token khi deploy | MVP | -| Flavor Selection | Chọn cấu hình tài nguyên CPU × RAM | MVP | -| Persistent Disk | Local disk `5Gi`mount tại `/home/user` | MVP | -| Setting Up Workspace | Màn hình provisioning với task list và polling | MVP | -| Gateway Password | One-time token để auth vào OpenClaw Gateway lần đầu | MVP | -| My Agents Dashboard | Quản lý instance: Running/Stopped, Open/Stop/Restart/Delete | MVP | -| Auto-shutdown | Tự dừng instance sau 24h idle | MVP | -| Multi-instance | Nhiều instance per user (paid plan) | Phase 2 | -| Deploy Node | Thêm node từ Gateway Dashboard | Phase 2 | - -*** - -## 2. User Stories (Gherkin Format) - -### Feature: 1-Click Deploy OpenClaw trên AgentBase - -*** - -#### US-01: Deploy OpenClaw với GreenNode MaaS (Happy path) - -**As a** GreenNode user muốn dùng AI Agent ngay, **I want** click "Deploy 1-Click" trên Marketplace và có instance OpenClaw sẵn sàng trong 40–60 giây, **So that** tôi có thể bắt đầu chat với AI Agent mà không cần setup gì. - -**Acceptance Criteria:** - -```gherkin -Feature: Deploy OpenClaw 1-Click với GreenNode MaaS - - Background: - Given người dùng đã đăng nhập GreenNode Portal - And người dùng chưa có OpenClaw instance nào - - Scenario: Deploy thành công với MaaS mặc định - When người dùng click "Deploy 1-Click" trên OpenClaw card tại Marketplace - And người dùng giữ nguyên lựa chọn "GreenNode MaaS" (mặc định) - And người dùng điền Tên OpenClaw và chọn Flavor - And người dùng click "Bắt đầu thiết lập" - Then màn hình "Setting Up Your Workspace" xuất hiện với 4 tasks - And 4 tasks lần lượt chuyển từ ◌ sang ✓: OpenClaw Token → AI Service Account → AI Service Token → Cloud Computer - And sau khi tất cả tasks hoàn thành, hệ thống tự redirect đến màn hình Deploy Success - And màn hình Deploy Success hiển thị instance name, trạng thái ONLINE, URL và gateway password - - Scenario: User chưa đăng nhập click Deploy - Given người dùng chưa đăng nhập GreenNode Portal - When người dùng click "Deploy 1-Click" trên Marketplace - Then hệ thống redirect đến trang GreenNode Login - And sau khi đăng nhập xong, hệ thống redirect về màn hình cấu hình (Screen 3) - - Scenario: User đã có instance đang chạy click Deploy lần 2 - Given người dùng đã có 1 OpenClaw instance với trạng thái Running - When người dùng click "Deploy 1-Click" trên Marketplace - Then hệ thống redirect thẳng về My Agents Dashboard - And hiển thị banner "Bạn đã có instance đang chạy" -``` - -*** - -#### US-02: Deploy OpenClaw với BYOK (Bring Your Own Key) - -**As a** user muốn dùng model AI từ provider bên ngoài, **I want** nhập API key của riêng mình khi cấu hình OpenClaw, **So that** tôi có thể dùng model yêu thích (gpt-4o, Claude, v.v.) mà không bị giới hạn vào GreenNode MaaS. - -**Acceptance Criteria:** - -```gherkin -Feature: Deploy OpenClaw với BYOK API key - - Background: - Given người dùng đã đăng nhập GreenNode Portal - And người dùng đang ở màn hình cấu hình (Screen 3) - - Scenario: BYOK deploy thành công - When người dùng chọn radio "Nhập API Key của bạn" - And người dùng chọn Provider là "OpenAI" - And người dùng nhập API Key hợp lệ - And người dùng chọn Model "gpt-4o" - And người dùng click "Bắt đầu thiết lập" - Then hệ thống gọi /api/v1/openclaw/validate-key để kiểm tra key - And sau khi validate thành công, hệ thống tiến hành provisioning - And instance được deploy với model đã chọn - - Scenario: BYOK key không hợp lệ - When người dùng chọn BYOK và nhập API key sai định dạng hoặc đã hết hạn - And người dùng click "Bắt đầu thiết lập" - Then hệ thống hiển thị lỗi inline bên dưới trường API Key: "API key không hợp lệ" - And nút "Bắt đầu thiết lập" bị block, không chuyển sang Screen 5 - - Scenario Outline: Validation form BYOK - Given người dùng đã chọn BYOK - When người dùng bỏ trống trường - And người dùng click "Bắt đầu thiết lập" - Then hệ thống hiển thị lỗi "" - - Examples: - | field | error_message | - | API Key | "Vui lòng nhập API Key" | - | Model | "Vui lòng chọn model" | - | Tên OpenClaw | "Vui lòng nhập tên instance" | -``` - -*** - -#### US-03: Cấu hình Channel Telegram khi deploy - -**As a** user muốn tích hợp OpenClaw với Telegram, **I want** cấu hình Telegram bot token ngay trong bước thiết lập, **So that** sau khi deploy tôi có thể chat với OpenClaw qua Telegram ngay lập tức. - -**Acceptance Criteria:** - -```gherkin -Feature: Cấu hình Telegram Channel khi deploy OpenClaw - - Background: - Given người dùng đang ở màn hình cấu hình (Screen 3) - - Scenario: Deploy với Telegram bot được cấu hình - When người dùng chọn Channel Provider là "Telegram" - And người dùng chọn Mode "Pairing" - And người dùng nhập Bot Token hợp lệ - And người dùng click "Bắt đầu thiết lập" - Then instance được deploy với Telegram bot đã kết nối - And người dùng có thể chat với OpenClaw qua Telegram ngay sau khi deploy - - Scenario: Bỏ qua cấu hình Channel - When người dùng không nhập Bot Token - And người dùng click "Bắt đầu thiết lập" - Then instance vẫn deploy thành công - And Channel có thể được cấu hình sau tại portal Settings → Config -``` - -*** - -#### US-04: Xem màn hình Provisioning - -**As a** user vừa submit form cấu hình, **I want** thấy tiến độ provisioning theo từng task, **So that** tôi biết hệ thống đang làm gì và ước lượng được thời gian chờ. - -**Acceptance Criteria:** - -```gherkin -Feature: Màn hình Setting Up Your Workspace - - Background: - Given người dùng vừa click "Bắt đầu thiết lập" từ Screen 3 - - Scenario: Hiển thị và hoàn thành provisioning - When màn hình "Setting Up Your Workspace" xuất hiện - Then hệ thống hiển thị 4 tasks theo thứ tự: OpenClaw Token, AI Service Account, AI Service Token, Cloud Computer - And mỗi task hiển thị spinner ◌ khi đang xử lý và ✓ khi hoàn thành - And hệ thống poll /api/v1/openclaw/instances/{id}/status mỗi 3 giây - And khi status = "ready", hệ thống tự redirect đến Screen 6 - - Scenario: Provisioning thất bại - When một trong 4 tasks bị lỗi hoặc timeout - Then hệ thống hiển thị trạng thái lỗi với link "Troubleshoot" - And hiển thị nút "Retry" - And instance không tính vào quota của user -``` - -*** - -#### US-05: Lấy gateway password sau khi deploy thành công - -**As a** user vừa deploy xong OpenClaw, **I want** thấy gateway password và URL của instance, **So that** tôi có thể đăng nhập vào OpenClaw Gateway Dashboard ngay lập tức. - -**Acceptance Criteria:** - -```gherkin -Feature: Màn hình Deploy Success - - Background: - Given provisioning đã hoàn thành thành công - - Scenario: Hiển thị đầy đủ thông tin instance - When màn hình Deploy Success xuất hiện - Then hệ thống hiển thị: instance name, trạng thái ONLINE, AI model, URL, gateway password, thời gian tạo - And gateway password chỉ hiển thị 1 lần duy nhất tại màn hình này - And có nút "Mở OpenClaw" để vào Gateway Dashboard - And có nút "Sao chép URL" và "Quản lý instance" - - Scenario: Mở OpenClaw từ màn hình Deploy Success - When người dùng click "Mở OpenClaw" - Then hệ thống redirect đến https://{instance-id}.openclaw.agentbase.vn - And người dùng dùng gateway password để auth lần đầu -``` - -*** - -#### US-06: Quản lý instance từ My Agents Dashboard - -**As a** user có OpenClaw instance đang chạy, **I want** xem và quản lý instance của mình từ My Agents Dashboard, **So that** tôi có thể stop, restart, xóa instance hoặc mở lại portal bất kỳ lúc nào. - -**Acceptance Criteria:** - -```gherkin -Feature: Quản lý OpenClaw Instance từ My Agents Dashboard - - Background: - Given người dùng đã đăng nhập GreenNode Portal - And người dùng đang ở trang My Agents - - Scenario: Xem danh sách instance theo trạng thái - When trang My Agents được load - Then hệ thống hiển thị 2 section: "Running 🟢" và "Stopped ⚪" - And mỗi instance card hiển thị: tên, trạng thái, AI model, version, tags - And section Stopped hiển thị empty state khi chưa có instance nào bị dừng - - Scenario: Mở lại OpenClaw đang Running - When người dùng click "Open" trên instance card có trạng thái Running - Then hệ thống redirect thẳng vào OpenClaw Gateway Dashboard - And không đi qua wizard/provisioning lại - - Scenario: Stop instance - When người dùng click "Stop" trên instance card - And xác nhận trong confirm dialog - Then instance chuyển sang trạng thái Stopped - And URL của instance không còn accessible - And card chuyển xuống section Stopped - - Scenario: Restart instance đã Stop - When người dùng click "Restart" trên instance đang Stopped - Then instance chuyển qua trạng thái Starting → Running - And URL hoạt động lại - And card chuyển lên section Running - - Scenario: Xóa instance - When người dùng click "Delete" trên instance card - And xác nhận trong confirm dialog - Then instance bị xóa vĩnh viễn - And quota được trả về - And vị trí card đổi thành slot "Deploy a new Agent" - - Scenario: Auto-shutdown sau 24h idle - Given instance không có request trong 24 giờ - When system cron job chạy - Then instance tự chuyển sang Stopped - And user nhận email thông báo - And user có thể Restart từ My Agents Dashboard -``` - -*** - -## 3. Functional Requirements - -### 3.1 Agent Marketplace — OpenClaw Card - -#### 3.1.1 Current State - -* Chưa có Agent Marketplace trong AgentBase. User muốn deploy OpenClaw phải tự tìm hiểu và thực hiện 13 bước thủ công. - -#### 3.1.2 Proposed Changes - -**Hero Banner:** - -| Field/Element | Description | Logic/Rule | Note | -| --------------- | ----------------------------------------- | -------------------------------- | -------------- | -| Headline | "Agent Marketplace" | Static | — | -| CTA button | "✅ Deploy OpenClaw With 1 Click!" | Click → kiểm tra auth → Screen 3 | Primary action | -| Hero background | Gradient dark card với 3D floating shapes | Visual only | — | - -**OpenClaw Featured Card:** - -| Field/Element | Description | Logic/Rule | Note | -| ------------- | ------------------------------------------------------ | --------------------- | ---------------------- | -| Badge | FEATURED + FREE | Static | Hiển thị nổi bật | -| Title | "OpenClaw by GreenNode" | Static | — | -| Description | "Personal AI agent architected for sovereign cloud..." | Static | Tối đa 2 dòng | -| Stats | Rating 4.9⭐ · 1,200+ Deploys · < 2 min Setup | Static (giai đoạn 1) | Cập nhật real-time sau | -| CTA | "🚀 Deploy 1-Click / No config needed" | Click → kiểm tra auth | Full-width, màu green | - -**Behavior:** - -* Click "Deploy 1-Click" hoặc hero CTA → kiểm tra auth - * Đã login → Screen 3 - * Chưa login → redirect GreenNode Login → sau login quay lại Screen 3 -* Đã có instance Running → redirect My Agents + banner thông báo - -*** - -### 3.2 Màn hình Cấu hình Deploy (Screen 3) - -#### 3.2.1 Current State - -* Không có. User phải tự tạo IAM Service Account, attach policy, tạo vCR repository, build Docker image, tạo Runtime thủ công. - -#### 3.2.2 Proposed Changes - -**Form Section 1 — AI Source:** - -| Field/Element | Type | Options | Description | -| ------------- | --------------------- | --------------------------------- | -------------------------------------------- | -| AI Source | Radio button | GreenNode MaaS / BYOK | Mặc định: GreenNode MaaS | -| BYOK Provider | Dropdown | OpenAI, Anthropic, Gemini, Custom | Chỉ hiển thị khi chọn BYOK | -| BYOK API Key | Text input (password) | — | Bắt buộc khi BYOK. Icon 👁 toggle visibility | -| BYOK Model | Dropdown | Động theo provider | Bắt buộc khi BYOK | - -**Form Section 2 — Instance Config:** - -| Field/Element | Type | Options | Description | -| ------------- | ---------- | ----------------- | ------------------------------------------ | -| Tên OpenClaw | Text input | — | Auto-fill:`openclaw/{username}`. Bắt buộc | -| Flavor | Dropdown | 2×4, 4×8, 8×16... | Bắt buộc. Mặc định:`2×4` | -| Disk | Read-only | `5Gi` | Fixed giai đoạn 1. Mount path:`/home/user` | - -**Form Section 3 — Channel Configuration:** - -| Field/Element | Type | Options | Description | -| ---------------- | ------------ | -------------------- | --------------------------------- | -| Channel Provider | Dropdown | Telegram | Mặc định: Telegram | -| Mode | Radio button | Pairing / Allow List | Mặc định: Pairing | -| Bot Token | Text input | — | Không bắt buộc. Cấu hình sau được | - -**Business Rules:** - -| Rule | Description | -| ----- | -------------------------------------------------------------------------------------------- | -| BR-01 | Khi chọn GreenNode MaaS, không hiển thị trường BYOK | -| BR-02 | Khi chọn BYOK, bắt buộc Provider + API Key + Model. Gọi validate-key trước khi submit | -| BR-03 | Tên OpenClaw auto-fill từ username, cho phép sửa. Không được trùng với instance đang Running | -| BR-04 | Disk `5Gi`cố định, không cho chỉnh trong MVP | -| BR-05 | Bot Token không bắt buộc — bỏ trống thì deploy không có Channel, cấu hình sau | -| BR-06 | 1 user chỉ có tối đa 1 instance Running (free tier) | - -*** - -### 3.3 Màn hình Provisioning — Setting Up Your Workspace (Screen 5) - -#### 3.3.1 Current State - -* Không có màn hình provisioning — deploy xong không biết trạng thái gì. - -#### 3.3.2 Proposed Changes - -**Task List:** - -| Task | Mô tả | Trạng thái | -| ------------------ | ------------------------------------------- | ---------- | -| OpenClaw Token | Tạo Identity và token xác thực cho instance | ◌ / ✓ / ✗ | -| AI Service Account | Tạo IAM Service Account kết nối MaaS | ◌ / ✓ / ✗ | -| AI Service Token | Lấy access token cho model AI | ◌ / ✓ / ✗ | -| Cloud Computer | Khởi động container OpenClaw | ◌ / ✓ / ✗ | - -**Behavior:** - -* Frontend poll `/api/v1/openclaw/instances/{id}/status` mỗi 3 giây -* Auto-redirect khi status = `ready` -* Nếu timeout (> 3 phút) hoặc task bị lỗi: hiển thị failed state + link Troubleshoot + nút Retry - -*** - -### 3.4 Màn hình Deploy Success (Screen 6) - -#### 3.4.1 Current State - -* Không có. - -#### 3.4.2 Proposed Changes - -**Instance Info Card:** - -| Field/Element | Description | Logic/Rule | Note | -| -------------------- | ------------------------------------ | ----------------------------------- | ------------------------- | -| Instance name | Ví dụ:`openclaw-nguyenvana-001` | Auto-generated | Read-only | -| Trạng thái | 🟢 ONLINE | Từ API | — | -| AI Model | Ví dụ:`gpt-5.4 · GreenNode MaaS` | Từ config | — | -| URL | `https://{id}.openclaw.agentbase.vn` | Auto-generated | Có nút copy | -| **Gateway password** | Token xác thực một lần | Chỉ hiển thị 1 lần tại màn hình này | Cảnh báo rõ ràng bên dưới | -| Thời gian tạo | Timestamp | Auto | — | - -**Business Rules:** - -| Rule | Description | -| ----- | -------------------------------------------------------------------------------------------------- | -| BR-07 | Gateway password hiển thị đúng 1 lần tại Screen 6. Sau khi user rời trang, không thể truy xuất lại | -| BR-08 | Nếu user cần reset gateway password, thực hiện từ My Agents Dashboard (flow Phase 2) | - -*** - -### 3.5 My Agents Dashboard (Screen 8) - -#### 3.5.1 Current State - -* AgentBase có màn hình Runtime list nhưng không có view theo-product "My Agents" dành riêng cho OpenClaw. - -#### 3.5.2 Proposed Changes - -**Danh sách Instance — Sections:** - -| Section | Điều kiện | Mô tả | -| ----------- | ----------------------------- | -------------------------------- | -| Running 🟢 | Có ít nhất 1 instance Running | Card grid với nút "Open" | -| Stopped ⚪ | Có ít nhất 1 instance Stopped | Card grid với nút "Restart" | -| Empty state | Chưa có instance nào | Icon + "Deploy a new Agent" slot | - -**Actions trên card:** - -| Action | Icon | Description | -| ------- | ---- | --------------------------------------------------- | -| Open | ↗ | Redirect vào OpenClaw Gateway Dashboard | -| Stop | ■ | Dừng instance. Hiện confirm dialog | -| Restart | ↺ | Khởi động lại instance Stopped | -| Delete | 🗑 | Xóa vĩnh viễn. Hiện confirm dialog với tên instance | - -*** - -## 4. UI/UX Specifications - -### 4.1 Color Palette - -| Role | GreenNode Portal | OpenClaw Gateway | -| -------------- | ------------------------------- | ---------------- | -| Background | `#F9FAFB`(page),`#FFFFFF`(card) | `#FFFFFF` | -| Top nav | `#111111`(dark) | `#FFFFFF` | -| Sidebar | `#FFFFFF`(white) | `#0A0C0A`(dark) | -| Accent / CTA | `#16A34A`(green) | `#16A34A`(green) | -| Text primary | `#111111` | `#111111` | -| Text secondary | `#6B7280` | `#555555` | -| Border | `#E5E7EB` | `#E0EAE0` | -| Error | `#EF4444` | `#EF4444` | -| Success | `#16A34A` | `#16A34A` | - -### 4.2 Screen 3 — Config Form Card - -| Element | Specification | -| ------------- | ---------------------------------------------------------------------------------------------- | -| Card width | 480px (center) | -| Card style | White bg,`border-radius: 12px`,`box-shadow: 0 4px 24px rgba(0,0,0,0.08)` | -| Radio buttons | Dạng card — full-width, 56px height,`border: 1.5px solid`, selected:`border-color: #16A34A` | -| BYOK section | Expandable dưới radio,`border-radius: 8px`, bg `#F9FAFB` | -| CTA button | Full-width, 48px height,`bg: #16A34A`,`color: #FFFFFF`,`border-radius: 8px` | -| Input fields | `height: 40px`,`border: 1px solid #D1D5DB`,`border-radius: 6px`, focus:`border-color: #16A34A` | - -### 4.3 Screen 5 — Provisioning Card - -| Element | Specification | -| ---------------------- | ----------------------------------------------------- | -| Card width | 480px (center) | -| Spinner | Arc spinner `#16A34A`, 48px, center | -| Task icon — pending | ◌`#9CA3AF` | -| Task icon — done | ✓`#16A34A` | -| Task icon — error | ✗`#EF4444` | -| Button "Connecting..." | Full-width, disabled state, bg `#16A34A`, opacity 60% | - -### 4.4 Screen 6 — Deploy Success Card - -| Element | Specification | -| ------------------ | ---------------------------------------------------------------------- | -| Success icon | ✅ check circle, 56px,`color: #16A34A`, glow ring `rgba(22,163,74,0.2)` | -| Instance info card | White bg,`border: 1px solid #E5E7EB`,`border-radius: 12px` | -| Gateway password | Monospace font,`bg: #F0FDF4`,`border: 1px solid #86EFAC`, hiển thị rõ | -| Warning text | `color: #D97706`, icon ⚠️, text "Password chỉ hiển thị 1 lần..." | -| Primary CTA | "Mở OpenClaw" — full-width,`bg: #16A34A` | - -### 4.5 Screen 8 — My Agents Dashboard - -| Element | Specification | -| ------------------- | -------------------------------------------------------------------------- | -| Section header | "Running (n) 🟢" / "Stopped (n) ⚪" —`font-weight: 600`,`font-size: 16px` | -| Card grid | 3 columns,`gap: 16px` | -| Instance card | White bg,`border: 1px solid #E5E7EB`,`border-radius: 12px`,`padding: 20px` | -| Status pill Running | `bg: #DCFCE7`,`color: #16A34A`,`border-radius: 9999px` | -| Status pill Stopped | `bg: #F3F4F6`,`color: #6B7280`,`border-radius: 9999px` | -| "Open" button | Full-width,`bg: #16A34A`,`color: #FFFFFF` | -| Actions menu | ⋮ icon → dropdown: Stop / Restart / Delete | - -*** - -## 5. Validation Rules - -### 5.1 Form Cấu hình Deploy (Screen 3) - -| Field | Rule | Error Message | -| ------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -| Tên OpenClaw | Bắt buộc. Pattern:`openclaw/[a-z0-9-]{3,32}`. Không trùng instance đang Running | "Tên không hợp lệ (chỉ chứa a-z, 0-9, dấu gạch ngang, 3–32 ký tự)" | -| Flavor | Bắt buộc, phải chọn từ danh sách | "Vui lòng chọn Flavor" | -| BYOK Provider | Bắt buộc khi chọn BYOK | "Vui lòng chọn Provider" | -| BYOK API Key | Bắt buộc khi BYOK. Gọi validate-key trước submit | "API key không hợp lệ hoặc đã hết hạn" | -| BYOK Model | Bắt buộc khi BYOK | "Vui lòng chọn Model" | - -### 5.2 Business Rules Validation - -| Rule | Description | -| ---------------- | ------------------------------------------------------------------------------------------------ | -| Quota 1 instance | Nếu đã có 1 instance Running → block deploy, redirect My Agents | -| BYOK key test | Validate key trước khi submit form — gọi `/api/v1/openclaw/validate-key`. Timeout 10 giây | -| Tên trùng lặp | Tên instance phải unique trong cùng Organization | -| Gateway password | Không bao giờ trả về qua API sau lần đầu. Không có endpoint "lấy lại password" trong giai đoạn 1 | - -*** - -## 6. Technical Notes - -### 6.1 Architecture - -``` -┌───────────────────────────────────────────────────────┐ -│ User Browser (Next.js Frontend) │ -│ Marketplace · Config wizard · My Agents · Success │ -└────────────────────────┬──────────────────────────────┘ - │ HTTPS REST API -┌────────────────────────▼──────────────────────────────┐ -│ AgentBase Backend — OpenClaw Orchestrator │ -│ ┌──────────────┐ ┌─────────────────┐ ┌──────────┐ │ -│ │ OpenClaw │ │ Key Provisioner │ │ Instance │ │ -│ │ Manager API │ │ (MaaS bridge) │ │ Lifecycle│ │ -│ └──────┬───────┘ └────────┬────────┘ └────┬─────┘ │ -└─────────┼───────────────────┼────────────────┼─────────┘ - │ │ │ - ┌──────▼──────┐ ┌────────▼────────┐ ┌───▼──────────┐ - │ AgentBase │ │ GreenNode MaaS │ │ AgentBase │ - │ Identity │ │ AIP API │ │ Runtime │ - │ Service │ │ (Internal) │ │ Service │ - └─────────────┘ └─────────────────┘ └──────┬───────┘ - │ - ┌────────▼───────┐ - │ Container: │ - │ OpenClaw │ - │ (port 8080) │ - │ Disk: 5Gi │ - │ mount /home/user│ - └─────────────────┘ -``` - -### 6.2 Dependencies - -| Service/Component | Type | Purpose | Version | -| -------------------------- | -------- | ------------------------------------------- | ------------- | -| GreenNode Portal Auth | Internal | SSO login, session management | — | -| AgentBase Identity Service | Internal | Tạo Identity cho mỗi instance | v1 | -| AgentBase Runtime Service | Internal | Deploy và quản lý container | v1 | -| GreenNode MaaS (AIP) | Internal | LLM API endpoint, model `gpt-5.4` | v1 | -| Container Registry (vCR) | Internal | Lưu OpenClaw container image | — | -| AgentBase Reverse Proxy | Internal | Subdomain routing `*.openclaw.agentbase.vn` | Nginx/Traefik | -| Telegram Bot API | External | Channel integration | — | - -### 6.3 Core Functionality - -| Functionality | Description | Technical Implementation | -| ------------------- | ---------------------------------------------- | ------------------------------------------------------------------------ | -| MaaS Auto-Provision | Tự động tạo MaaS API key cho instance | POST `/internal/api-keys/provision`→ lưu vào Identity Service | -| BYOK Secure Storage | Lưu trữ API key bên thứ 3 an toàn | Mã hóa AES-256 at rest, chỉ decrypt khi inject vào container | -| Env Var Injection | Inject toàn bộ config vào container lúc deploy | AgentBase Runtime contract: inject `OPENAI_*`,`OPENCLAW_*`,`GREENNODE_*` | -| Gateway Password | One-time auth token cho OpenClaw Gateway | Generate ngẫu nhiên, lưu hash, chỉ trả về plain text 1 lần | -| Persistent Disk | Local volume `5Gi`cho workspace | Mount tại `/home/user`, survive restart, lost on delete | -| Subdomain Routing | `{id}.openclaw.agentbase.vn`→ container | Reverse proxy lookup Runtime endpoint theo instance ID | -| Auto-shutdown | Tự dừng sau 24h không có request | Cron job kiểm tra `last_request_at`trên mỗi instance | - -**Deploy Flow — Data Flow:** - -1. User submit form Screen 3 → POST `/api/v1/openclaw/deploy` -2. Backend: validate input → provision MaaS key (hoặc encrypt BYOK key) → tạo Identity → tạo Runtime với env vars + disk config -3. Frontend poll `/api/v1/openclaw/instances/{id}/status` mỗi 3s -4. Runtime status = `ready` → trả về `portal_url` + `gateway_password` → redirect Screen 6 - -**Key Environment Variables:** - -| Variable | Mô tả | Source | -| ---------------------------- | ------------------------------------------------ | ------------------------------ | -| `OPENAI_API_KEY` | API key để OpenClaw gọi LLM | Injected by AgentBase Runtime | -| `OPENAI_BASE_URL` | Endpoint URL của LLM provider | Injected by AgentBase Runtime | -| `OPENAI_MODEL` | Model name, default:`gpt-5.4` | Injected by AgentBase Runtime | -| `OPENCLAW_INSTANCE_ID` | Định danh instance | Injected by AgentBase Runtime | -| `OPENCLAW_GATEWAY_PASSWORD` | Gateway token auth lần đầu | Injected by AgentBase Runtime | -| `OPENCLAW_WORKSPACE` | Mount path persistent disk, default:`/home/user` | Injected by AgentBase Runtime | -| `OPENCLAW_DISK_SIZE` | Dung lượng persistent disk, default:`5Gi` | Injected by AgentBase Runtime | -| `OPENCLAW_CHANNEL_PROVIDER` | Channel provider (telegram) | Injected by AgentBase Runtime | -| `OPENCLAW_CHANNEL_BOT_TOKEN` | Bot token cho channel | Injected by AgentBase Runtime | -| `OPENCLAW_CHANNEL_MODE` | Mode: pairing / allow\_list | Injected by AgentBase Runtime | -| `GREENNODE_AGENT_IDENTITY` | Identity của agent trên AgentBase | Auto-inject (Runtime contract) | -| `GREENNODE_CLIENT_ID` | IAM credentials | Auto-inject (Runtime contract) | -| `GREENNODE_CLIENT_SECRET` | IAM credentials | Auto-inject (Runtime contract) | - -> **Lưu ý bảo mật** : OpenClaw dùng biến `OPENAI_API_KEY` và `OPENAI_BASE_URL` (OpenAI-compatible). AgentBase inject đúng tên biến này → không cần patch OpenClaw source code. - -### 6.4 High Availability & Resilience - -| Aspect | Strategy | Details | -| ---------------------- | ---------------------- | ------------------------------------------------ | -| **Redundancy** | Per-instance isolated | Mỗi user 1 container riêng, không share | -| **Failover** | Manual (giai đoạn 1) | User tự Restart từ My Agents khi instance lỗi | -| **Provisioning retry** | Auto-retry 3 lần | Backend retry mỗi 30s khi provisioning task fail | -| **Auto-shutdown** | Idle timeout 24h | Bảo toàn tài nguyên, user nhận email notify | -| **Disk persistence** | PersistentVolume `5Gi` | Survive restart, bị xóa khi delete instance | - -**SLA Targets:** - -| Metric | Target | Measurement | -| --------------------------- | ---------- | ------------------------------------------------ | -| Availability per instance | 99.5% | Uptime sau deploy thành công | -| Provisioning time best case | 40–60 giây | Từ submit form → status ready (confirmed by dev) | -| Provisioning time P95 | < 120 giây | Từ submit form → status ready | -| Portal load time | < 1 giây | Time to interactive trên Marketplace | - -### 6.5 Operations & Stability - -#### Monitoring & Alerting - -| Metric | Threshold | Alert Level | Action | -| ------------------------- | -------------------------------------- | ----------- | --------------------- | -| Provisioning failure rate | > 5% | Critical | Page on-call | -| Instance deploy time P95 | > 120 giây (expected best case 40–60s) | Warning | Investigate infra | -| BYOK validate-key latency | > 5 giây | Warning | Log + notify user | -| Auto-shutdown cron lag | > 1 giờ | Warning | Check cron job health | - -#### API Endpoints - -| Method | Endpoint | Mô tả | -| -------- | ----------------------------------------- | ----------------------------- | -| `POST` | `/api/v1/openclaw/deploy` | Tạo mới OpenClaw instance | -| `GET` | `/api/v1/openclaw/instances` | Liệt kê instances của user | -| `GET` | `/api/v1/openclaw/instances/{id}` | Chi tiết 1 instance | -| `GET` | `/api/v1/openclaw/instances/{id}/status` | Poll deployment status | -| `POST` | `/api/v1/openclaw/instances/{id}/stop` | Stop instance | -| `POST` | `/api/v1/openclaw/instances/{id}/restart` | Restart instance | -| `DELETE` | `/api/v1/openclaw/instances/{id}` | Xóa instance | -| `POST` | `/api/v1/openclaw/validate-key` | Test BYOK API key | -| `GET` | `/api/v1/maas/models` | Danh sách model MaaS khả dụng | -| `GET` | `/api/v1/openclaw/flavors` | Danh sách flavor khả dụng | - -*** - -## 7. Success Metrics - -| Metric | Baseline | Target (3 tháng) | Measurement | -| -------------------------------------------------- | -------- | ---------------- | ------------------------------------ | -| Số instance OpenClaw được tạo | 0 | 500+ | AgentBase analytics | -| Tỉ lệ hoàn thành wizard (không bỏ giữa chừng) | — | > 70% | Funnel tracking Screen 3 → 6 | -| Thời gian trung bình từ "Deploy" → "Chat đầu tiên" | — | < 3 phút | Từ submit form đến API call đầu tiên | -| DAU trên portal OpenClaw | — | 200+ | Gateway request logs | -| Tỉ lệ chuyển đổi BYOK → MaaS | — | > 20% | Provider field analytics | -| NPS score sau lần dùng đầu | — | > 40 | In-app survey | -| Tỉ lệ user quay lại trong 7 ngày | — | > 40% | Session analytics | -| Tỉ lệ cấu hình Channel (Telegram) khi deploy | — | > 30% | Bot Token field fill rate | - -*** - -## 8. Risks & Mitigations - -| Risk | Impact | Mitigation | -| -------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------- | -| OpenClaw không chạy được headless với env var inject (cần patch source) | Cao — block toàn bộ MVP | PoC ngay tuần 1: test inject `OPENAI_API_KEY`vào container OpenClaw trước khi dev | -| MaaS chưa có API internal để provision key tự động | Cao — block MaaS path | Confirm với MaaS team trước kick-off. Nếu chưa có: BYOK-only cho MVP | -| OpenClaw license không cho phép deploy dạng SaaS | Trung bình — rủi ro pháp lý | Check license (MIT/Apache). Nếu cần: add credit footer + thông báo | -| Free tier quota 100K tokens/ngày không đủ để trải nghiệm tốt | Trung bình — UX kém, churn | A/B test quota level sau MVP; hiển thị token counter trên Gateway | -| Subdomain wildcard SSL `*.openclaw.agentbase.vn`chưa sẵn sàng | Thấp — delay routing | Confirm wildcard cert với infra team trước Sprint 1 | -| User quên gateway password — không có flow reset giai đoạn 1 | Trung bình — support burden | Document rõ trong UI. Thiết kế flow "Reset gateway password" cho Phase 2 | -| Provisioning timeout do infra tải cao | Trung bình — UX xấu | Retry 3 lần với backoff. Hiển thị Troubleshoot link rõ ràng | -| Scope creep từ Channel integration (Allow List cần thêm UI nhập user list) | Trung bình — chậm deadline | Confirm UX "Allow List" với Design: nếu cần UI phức tạp → defer sang Phase 2 | - -*** - -## 9. Appendix - -### A. Glossary - -| Term | Definition | -| ----------------- | ------------------------------------------------------------------------------------------- | -| MaaS | Model as a Service — GreenNode hosted LLM API tại `maas-llm-aiplatform-hcm.api.vngcloud.vn` | -| BYOK | Bring Your Own Key — user tự cung cấp API key từ provider bên ngoài | -| Gateway Password | One-time token để auth lần đầu vào OpenClaw Gateway Dashboard | -| Flavor | Cấu hình tài nguyên container: vCPU × RAM GB (ví dụ:`2×4`= 2 vCPU, 4GB RAM) | -| Identity | Định danh agent trong AgentBase Identity Service | -| AgentBase Runtime | Service quản lý vòng đời container agent trên AgentBase | -| Pairing Mode | Telegram channel mode: 1 OpenClaw ↔ 1 Telegram user | -| Allow List Mode | Telegram channel mode: 1 OpenClaw ↔ danh sách Telegram user được phép | - -### B. So sánh với OpenClawCloud - -| Tiêu chí | OpenClawCloud | AgentBase 1-Click | -| ------------------- | ---------------------- | --------------------------------- | -| Hạ tầng | Claw.Cloud VPS | GreenNode (VNG Cloud) | -| Free tier | 7 ngày compute | TBD (quota-based) | -| AI Models | GLM-4.7, GLM-5, Claude | GreenNode MaaS (`gpt-5.4`) + BYOK | -| Auto key inject | Có (proprietary) | Có (AgentBase Identity) | -| Sovereign | Không | Có (data ở VN) | -| SSO nội bộ VNG | Không | Có | -| Channel integration | Không | Telegram (MVP) | -| Flavor selection | Không | Có | -| Persistent disk | Có | `5Gi`mount `/home/user` | -| Giá | $0–$39.99/tháng | TBD (align Sales) | - -### C. Figma Design Reference - -| Screen | Figma Node | Mô tả | -| ------------------------------- | ----------- | -------------------------------------------------------- | -| Screen 1 — Agent Marketplace | `668:24274` | GreenNode Portal, Marketplace với OpenClaw featured card | -| Screen 3 — Config AI + Instance | `649:24062` | Form cấu hình: AI source, tên, flavor, channel | -| Screen 5 — Setting Up Workspace | `671:25754` | Provisioning task list | -| Screen 6 — Deploy Success | `649:24157` | Light mode, gateway password | -| Screen 7 — Gateway Dashboard | `649:24231` | Chat UI, Dashboard/Logs/Terminal tabs | -| Screen 8 — My Agents | `671:25091` | Running/Stopped sections | - -**Figma file** : `-UI- AgentBase` (fileKey: `IH7ERLh3KfvztmTe6qD9pW`) - -### D. References - -* [AgentBase Product Overview](https://github.com/vngcloud/docs/blob/main/Vietnamese/ai-stack/agent-base/AI-Agent-Normal/Product-Overview-Agentbase.md) -* [AgentBase Runtime Contract](https://github.com/vngcloud/docs/blob/main/Vietnamese/ai-stack/greennode-agentbase-skills-main/.claude/skills/agentbase/references/runtime-contract.md) -* [OpenClawCloud](https://open.claw.cloud/) -* [GreenNode MaaS Endpoint](https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1) - -### E. Changelog - -| Version | Ngày | Tác giả | Nội dung | -| -------- | ---------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **v1.3** | 2026-03-30 | Product Team | Đổi MaaS default model →`gpt-5.4`; thêm persistent disk `5Gi`mount `/home/user`; restructure toàn bộ theo chuẩn PRD 8-section; update provisioning time best case 40–60s (confirmed by dev); chuyển Changelog sang Appendix E | -| **v1.2** | 2026-03-27 | Product Team | Sync screen flow với Figma design mới: Agent Marketplace thay dark landing page; bỏ Auth Popup riêng; Screen 3 thêm Flavor + Channel config; Screen 6 light mode + gateway password; Gateway Dashboard redesign (tabs + sidebar mới); My Agents → Running/Stopped sections | -| **v1.1** | 2026-03-25 | Product Team | Refactor flow UX: thay wizard 4 bước bằng 2-path auth; bỏ Review & Deploy screen; thay Deploying Progress bằng "Setting Up Your Workspace"; cập nhật Screen 7 và 8 sang light mode | -| **v1.0** | 2026-03-25 | Product Team | Khởi tạo PRD | - -*** - -_Xem chi tiết lịch sử thay đổi tại Appendix E. Mọi thay đổi cần được review bởi Product Owner trước khi cập nhật._ diff --git a/Vietnamese/ai-stack/ai-gateway/README.md b/Vietnamese/ai-stack/ai-gateway/README.md index faa7c72be..00f748e09 100644 --- a/Vietnamese/ai-stack/ai-gateway/README.md +++ b/Vietnamese/ai-stack/ai-gateway/README.md @@ -4,3 +4,30 @@ description: Cổng kết nối thông minh cho dịch vụ AI # AI Gateway +**AI Gateway** là cổng kết nối tập trung giúp bạn tích hợp nhiều AI model từ các nhà cung cấp khác nhau (OpenAI, Google, Deepseek...) thông qua một endpoint duy nhất — giảm độ phức tạp khi chuyển đổi model, hỗ trợ giám sát tập trung, tối ưu chi phí và bảo mật dữ liệu. + +*** + +## Tổng quan + +| Nhóm tính năng | Mô tả | +|---|---| +| **Đa mô hình (Multi-LLM)** | Tích hợp linh hoạt nhiều LLM từ nhiều provider qua một cổng kết nối duy nhất | +| **Giám sát** | Theo dõi hiệu suất và hoạt động qua metrics và logs, bao gồm cả các chỉ số latency chi tiết | +| **Kiểm soát truy cập** | Quản lý **Authentication Token** và đặt giới hạn Rate theo số request hoặc số token | +| **Tối ưu chi phí** | Caching giúp giảm số request tới model, tiết kiệm chi phí và cải thiện tốc độ phản hồi | + +*** + +## Bắt đầu + +| Tôi muốn... | Đi đến | +|---|---| +| Hiểu AI Gateway là gì và giải quyết vấn đề gì | [AI Gateway là gì?](ai-gateway-la-gi.md) | +| Khởi tạo gateway, gọi request đầu tiên và giám sát hoạt động | [Bắt đầu với AI Gateway](bat-dau-voi-ai-gateway.md) | +| Thêm, sửa hoặc xóa provider và model trên gateway | [Làm việc với Provider và Model](ai-gateway/lam-viec-voi-provider-va-model/README.md) | +| Tạo và quản lý Authentication Token | [Làm việc với Authentication Token](ai-gateway/lam-viec-voi-authentication-token.md) | +| Giảm chi phí và độ trễ bằng caching | [Caching](ai-gateway/caching-coming-soon.md) | +| Giới hạn số request hoặc số token theo khoảng thời gian | [Giới hạn Rate](ai-gateway/rate-limit-coming-soon.md) | +| Tìm hiểu cách AI Gateway bảo vệ thông tin nhạy cảm | [Bảo mật](bao-mat.md) | +| Xem chính sách tính giá của dịch vụ | [Cách tính giá](cach-tinh-gia.md) | diff --git a/Vietnamese/ai-stack/ai-gateway/ai-gateway/lam-viec-voi-provider-va-model/README.md b/Vietnamese/ai-stack/ai-gateway/ai-gateway/lam-viec-voi-provider-va-model/README.md index 21a1de330..dc1b287c4 100644 --- a/Vietnamese/ai-stack/ai-gateway/ai-gateway/lam-viec-voi-provider-va-model/README.md +++ b/Vietnamese/ai-stack/ai-gateway/ai-gateway/lam-viec-voi-provider-va-model/README.md @@ -1,6 +1,6 @@ # Làm việc với Provider và Model -goài việc thêm model trong lúc tạo AI Gateway, bạn có thể **thêm mới**, **chỉnh sửa**, hoặc **xóa model** như sau: +Ngoài việc thêm model trong lúc tạo AI Gateway, bạn có thể **thêm mới**, **chỉnh sửa**, hoặc **xóa model** như sau: **Bước 1:** Truy cập cấu hình Provider & Model diff --git a/Vietnamese/ai-stack/ai-gateway/bat-dau-voi-ai-gateway/giam-sat-hoat-dong-cua-ai-gateway.md b/Vietnamese/ai-stack/ai-gateway/bat-dau-voi-ai-gateway/giam-sat-hoat-dong-cua-ai-gateway.md deleted file mode 100644 index 16f9da1b8..000000000 --- a/Vietnamese/ai-stack/ai-gateway/bat-dau-voi-ai-gateway/giam-sat-hoat-dong-cua-ai-gateway.md +++ /dev/null @@ -1,45 +0,0 @@ -# Giám sát hoạt động của AI Gateway - -Để theo dõi và phân tích hoạt động của một AI Gateway đang hoạt động, bạn có thể giám sát thông qua: - -## Metric - -Tại giao diện chi tiết của một Gateway, chọn tab **Monitor** để theo dõi các chỉ số thời gian thực được thể hiện qua biểu đồ bao gồm: - -* **Requests**: Tổng số lượng request đã được gửi tới AI Gateway. -* **Errors**: Số request đã được gửi tới AI Gateway và được nhận kết quả lỗi. -* **Tokens**: Số lượng token đã sử dụng, bao gồm: - * `input`: token đầu vào (câu hỏi của bạn). - * `output`: token đầu ra (kết quả từ LLM Model). - -Bạn có thể tùy chỉnh khoảng thời gian quan sát (15m, 30m, 1h, 2h, v.v.) và lọc theo Provider hoặc Model cụ thể. - -
- -## Logs - -Tại giao diện chi tiết của một Gateway, chọn tab **Log** để xem danh sách tất cả các request đã gửi qua Gateway. - -Tại đây, bạn có thể danh sách request được gửi tới AI Gateway bao gồm: - -* **Time:** thời gian gửi request. -* **Status:** trạng thái của request, bao gồm **Success**, **Error** hoặc **Timeout**. -* **Model:** tên model được sử dụng. -* **Tokens:** số lượng token input/ output. -* **Duration:** tổng thời gian xử lý request. - -Bạn có thể tùy chỉnh khoảng thời gian quan sát (24h, 1d, 2d,...) và lọc theo Status cụ thể. - -
- -Ngoài ra, bạn có thể xem chi tiết một request bằng cách: - -* Nhấn vào biểu tượng **Detail** cột **Action** để mở **Detail Log**. -* Tại đây bạn sẽ thấy: - * **Input**: Nội dung câu hỏi hoặc prompt gốc bạn gửi vào. - * **Output**: Kết quả trả về từ LLM Model. - * **Thông tin bổ sung**: host, model, thời gian phản hồi,... - -
- -
diff --git a/Vietnamese/ai-stack/ai-gateway/bat-dau-voi-ai-gateway/goi-request-toi-ai-gateway.md b/Vietnamese/ai-stack/ai-gateway/bat-dau-voi-ai-gateway/goi-request-toi-ai-gateway.md deleted file mode 100644 index e6b415755..000000000 --- a/Vietnamese/ai-stack/ai-gateway/bat-dau-voi-ai-gateway/goi-request-toi-ai-gateway.md +++ /dev/null @@ -1,50 +0,0 @@ -# Gọi request tới AI Gateway - -Sau khi khởi tạo xong một AI Gateway, bạn có thể bắt đầu gửi request đến mô hình AI đã cấu hình theo các bước sau: - -**Bước 1:** Truy cập [AI Gateway Portal](http://aigateway.console.greennode.ai/), tìm đến gateway mà bạn vừa tạo. - -**Bước 2:** Trong mục **Providers & Model**, tìm mô hình AI bạn đã cấu hình. Tại mô hình đó, nhấn vào biểu tượng **Curl command** để lấy câu lệnh mẫu. - -
- -**Bước 3:** Sao chép đoạn lệnh `curl` được hiển thị và thực thi lệnh đó trên máy tính cá nhân của bạn (qua Terminal hoặc Command Prompt). - -
- -Ví dụ: - -```bash -curl -X POST https://user-60108-gateway-0b50037b-93.ai-gateway.vngcloud.vn/deepseek/deepseek-chat/chat/completions \ - --header 'Authorization: Bearer {AUTHENTICATION_TOKEN}' \ - --header 'Content-Type: application/json' \ - --data '{ - "model": "deepseek-chat", - "messages": [ - { - "role": "user", - "content": "What is AI?" - } - ] - }' -``` - -**Lưu ý:** - -* Thay thế `{AUTHENTICATION_TOKEN}` bằng token được cung cấp sau khi tạo Gateway. -* Bạn có thể chỉnh sửa nội dung của prompt (nội dung câu hỏi) trong phần `"content"` để phù hợp với mục đích sử dụng của mình. -* Nếu AI Gateway mà bạn đang sử dụng **được bật chế độ xác thực (Authenticated Gateway)**, bạn cần t**hêm một header tên là `cf-aig-authorization`** vào request HTTP của bạn. - -Ví dụ, thay vì dùng header thông thường kiểu: - -```http -Authorization: Bearer {AUTHENTICATION_TOKEN} -``` - -Bạn phải dùng: - -```http -cf-aig-authorization: Bearer {AUTHENTICATION_TOKEN} -``` - -Sau khi thực hiện, bạn sẽ nhận được phản hồi từ mô hình AI theo đúng định dạng JSON. diff --git a/Vietnamese/ai-stack/ai-gateway/bat-dau-voi-ai-gateway/khoi-tao-ai-gateway.md b/Vietnamese/ai-stack/ai-gateway/bat-dau-voi-ai-gateway/khoi-tao-ai-gateway.md deleted file mode 100644 index 7d43531e9..000000000 --- a/Vietnamese/ai-stack/ai-gateway/bat-dau-voi-ai-gateway/khoi-tao-ai-gateway.md +++ /dev/null @@ -1,22 +0,0 @@ -# Khởi tạo AI Gateway - -Để bắt đầu sử dụng AI Gateway trên GreenNode, bạn hãy thực hiện theo các bước sau: - -**Bước 1:** Truy cập giao diện AI Gateway tại GreenNode Console thông qua đường dẫn: [http://aigateway.console.greennode.ai/](http://aigateway.console.greennode.ai/) - -**Bước 2:** Trong menu bên trái, chọn mục **AI Gateway**, sau đó nhấn vào nút **Create an AI Gateway**. - -
- -**Bước 3:** Tại màn hình **Tạo Gateway mới**, vui lòng điền đầy đủ các thông tin sau: - -* **AI Gateway Name:** Đặt tên dễ nhớ cho gateway của bạn. Tên này chỉ được chứa các ký tự **a–z, A–Z, 0–9, dấu gạch dưới (\_) hoặc dấu gạch ngang (-)**, và có độ dài từ **5 đến 50 ký tự**. -* **Model Provider:** - * Chọn nhà cung cấp mô hình AI bạn muốn kết nối như **OpenAI, Anthropic, Google, DeepSeek**. - * **API Key:** Nhập **API Key** tương ứng từ nhà cung cấp. Nếu chưa có, bạn có thể nhấn **Get API Key** — chúng tôi sẽ chuyển bạn đến trang tương ứng để lấy thông tin. - * **Chọn mô hình (Model):** Lựa chọn mô hình AI bạn muốn sử dụng (ví dụ: _gemini-1.5_, _gemini-2.0_,...). Nếu muốn xem toàn bộ danh sách, hãy nhấn **View full list** để hiển thị tất cả các model mà chúng tôi hỗ trợ. -* **Gateway Config:** Mặc định, hệ thống sẽ bật tính năng **Authenticated Gateway**. Một **authenticated token** sẽ được tạo tự động – bạn có thể sử dụng token này để gửi request đến AI Gateway. - -**Bước 4**: Chọn Create an AI Gateway, AI Gateway của bạn sẽ được khởi tạo và sẵn sàng để sử dụng. - -
diff --git a/Vietnamese/ai-stack/ai-platform/model-registry/import-vllm-model.md b/Vietnamese/ai-stack/ai-platform/model-registry/import-vllm-model.md index 6400b28ae..444721ae2 100644 --- a/Vietnamese/ai-stack/ai-platform/model-registry/import-vllm-model.md +++ b/Vietnamese/ai-stack/ai-platform/model-registry/import-vllm-model.md @@ -5,7 +5,7 @@ * Đăng nhập với GreenNode account của bạn và truy cập tới [Model Registry Dashboard](https://aiplatform.console.greennode.ai/registry). * Tìm và nhấn vào nút "Import a model registry" (Nhập một model registry). -## Bước 2: Truy cập Model Registry +## Bước 2: Cấu hình Model Registry * **Region & Model registry name**: Chọn region và tên cụ thể cho model của bạn. * **Container**: Chọn option Pre-built container để sử dụng các framework được hỗ trợ.