docs: reorganize documentation into i18n folder structure (#466)

* docs: reorganize docs into en/cn/ja folders - Move documentation files into language-specific folders (en, cn, ja) - Add Chinese and Japanese translations for all docs - Extract Docker section from README to separate doc file - Update README to link to new doc locations * docs: fix links to new docs folder structure * docs: update README and provider docs * docs: fix broken import statements in cloudflare deploy guides * docs: sync CN/JA READMEs with EN structure and fix all paths
2026-01-02 14:22:28 +08:00 · 2025-12-31 00:04:32 +09:00
parent 24afa0b58a
commit aaa2938dac
15 changed files with 1262 additions and 268 deletions
--- a/docs/en/ai-providers.md
+++ b/docs/en/ai-providers.md
@@ -0,0 +1,236 @@
+# AI Provider Configuration
+
+This guide explains how to configure different AI model providers for next-ai-draw-io.
+
+## Quick Start
+
+1. Copy `.env.example` to `.env.local`
+2. Set your API key for your chosen provider
+3. Set `AI_MODEL` to your desired model
+4. Run `npm run dev`
+
+## Supported Providers
+
+### Doubao (ByteDance Volcengine)
+
+> **Free tokens**: Register on the [Volcengine ARK platform](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new&utm_campaign=doubao&utm_content=aidrawio&utm_medium=github&utm_source=coopensrc&utm_term=project) to get 500K free tokens for all models!
+
+```bash
+DOUBAO_API_KEY=your_api_key
+AI_MODEL=doubao-seed-1-8-251215  # or other Doubao model
+```
+
+### Google Gemini
+
+```bash
+GOOGLE_GENERATIVE_AI_API_KEY=your_api_key
+AI_MODEL=gemini-2.0-flash
+```
+
+Optional custom endpoint:
+
+```bash
+GOOGLE_BASE_URL=https://your-custom-endpoint
+```
+
+### OpenAI
+
+```bash
+OPENAI_API_KEY=your_api_key
+AI_MODEL=gpt-4o
+```
+
+Optional custom endpoint (for OpenAI-compatible services):
+
+```bash
+OPENAI_BASE_URL=https://your-custom-endpoint/v1
+```
+
+### Anthropic
+
+```bash
+ANTHROPIC_API_KEY=your_api_key
+AI_MODEL=claude-sonnet-4-5-20250514
+```
+
+Optional custom endpoint:
+
+```bash
+ANTHROPIC_BASE_URL=https://your-custom-endpoint
+```
+
+### DeepSeek
+
+```bash
+DEEPSEEK_API_KEY=your_api_key
+AI_MODEL=deepseek-chat
+```
+
+Optional custom endpoint:
+
+```bash
+DEEPSEEK_BASE_URL=https://your-custom-endpoint
+```
+
+### SiliconFlow (OpenAI-compatible)
+
+```bash
+SILICONFLOW_API_KEY=your_api_key
+AI_MODEL=deepseek-ai/DeepSeek-V3  # example; use any SiliconFlow model id
+```
+
+Optional custom endpoint (defaults to the recommended domain):
+
+```bash
+SILICONFLOW_BASE_URL=https://api.siliconflow.com/v1  # or https://api.siliconflow.cn/v1
+```
+
+### SGLang
+
+```bash
+SGLANG_API_KEY=your_api_key
+AI_MODEL=your_model_id
+```
+
+Optional custom endpoint:
+
+```bash
+SGLANG_BASE_URL=https://your-custom-endpoint/v1
+```
+
+### Azure OpenAI
+
+```bash
+AZURE_API_KEY=your_api_key
+AZURE_RESOURCE_NAME=your-resource-name  # Required: your Azure resource name
+AI_MODEL=your-deployment-name
+```
+
+Or use a custom endpoint instead of resource name:
+
+```bash
+AZURE_API_KEY=your_api_key
+AZURE_BASE_URL=https://your-resource.openai.azure.com  # Alternative to AZURE_RESOURCE_NAME
+AI_MODEL=your-deployment-name
+```
+
+Optional reasoning configuration:
+
+```bash
+AZURE_REASONING_EFFORT=low      # Optional: low, medium, high
+AZURE_REASONING_SUMMARY=detailed  # Optional: none, brief, detailed
+```
+
+### AWS Bedrock
+
+```bash
+AWS_REGION=us-west-2
+AWS_ACCESS_KEY_ID=your_access_key_id
+AWS_SECRET_ACCESS_KEY=your_secret_access_key
+AI_MODEL=anthropic.claude-sonnet-4-5-20250514-v1:0
+```
+
+Note: On AWS (Lambda, EC2 with IAM role), credentials are automatically obtained from the IAM role.
+
+### OpenRouter
+
+```bash
+OPENROUTER_API_KEY=your_api_key
+AI_MODEL=anthropic/claude-sonnet-4
+```
+
+Optional custom endpoint:
+
+```bash
+OPENROUTER_BASE_URL=https://your-custom-endpoint
+```
+
+### Ollama (Local)
+
+```bash
+AI_PROVIDER=ollama
+AI_MODEL=llama3.2
+```
+
+Optional custom URL:
+
+```bash
+OLLAMA_BASE_URL=http://localhost:11434
+```
+
+### Vercel AI Gateway
+
+Vercel AI Gateway provides unified access to multiple AI providers through a single API key. This simplifies authentication and allows you to switch between providers without managing multiple API keys.
+
+**Basic Usage (Vercel-hosted Gateway):**
+
+```bash
+AI_GATEWAY_API_KEY=your_gateway_api_key
+AI_MODEL=openai/gpt-4o
+```
+
+**Custom Gateway URL (for local development or self-hosted Gateway):**
+
+```bash
+AI_GATEWAY_API_KEY=your_custom_api_key
+AI_GATEWAY_BASE_URL=https://your-custom-gateway.com/v1/ai
+AI_MODEL=openai/gpt-4o
+```
+
+Model format uses `provider/model` syntax:
+
+-   `openai/gpt-4o` - OpenAI GPT-4o
+-   `anthropic/claude-sonnet-4-5` - Anthropic Claude Sonnet 4.5
+-   `google/gemini-2.0-flash` - Google Gemini 2.0 Flash
+
+**Configuration notes:**
+
+-   If `AI_GATEWAY_BASE_URL` is not set, the default Vercel Gateway URL (`https://ai-gateway.vercel.sh/v1/ai`) is used
+-   Custom base URL is useful for:
+    -   Local development with a custom Gateway instance
+    -   Self-hosted AI Gateway deployments
+    -   Enterprise proxy configurations
+-   When using a custom base URL, you must also provide `AI_GATEWAY_API_KEY`
+
+Get your API key from the [Vercel AI Gateway dashboard](https://vercel.com/ai-gateway).
+
+## Auto-Detection
+
+If you only configure **one** provider's API key, the system will automatically detect and use that provider. No need to set `AI_PROVIDER`.
+
+If you configure **multiple** API keys, you must explicitly set `AI_PROVIDER`:
+
+```bash
+AI_PROVIDER=google  # or: openai, anthropic, deepseek, siliconflow, doubao, azure, bedrock, openrouter, ollama, gateway, sglang
+```
+
+## Model Capability Requirements
+
+This task requires exceptionally strong model capabilities, as it involves generating long-form text with strict formatting constraints (draw.io XML).
+
+**Recommended models**:
+
+-   Claude Sonnet 4.5 / Opus 4.5
+
+**Note on Ollama**: While Ollama is supported as a provider, it's generally not practical for this use case unless you're running high-capability models like DeepSeek R1 or Qwen3-235B locally.
+
+## Temperature Setting
+
+You can optionally configure the temperature via environment variable:
+
+```bash
+TEMPERATURE=0  # More deterministic output (recommended for diagrams)
+```
+
+**Important**: Leave `TEMPERATURE` unset for models that don't support temperature settings, such as:
+- GPT-5.1 and other reasoning models
+- Some specialized models
+
+When unset, the model uses its default behavior.
+
+## Recommendations
+
+-   **Best experience**: Use models with vision support (GPT-4o, Claude, Gemini) for image-to-diagram features
+-   **Budget-friendly**: DeepSeek offers competitive pricing
+-   **Privacy**: Use Ollama for fully local, offline operation (requires powerful hardware)
+-   **Flexibility**: OpenRouter provides access to many models through a single API