diff --git a/NOTICE b/NOTICE index e1015a9c..b5a09205 100644 --- a/NOTICE +++ b/NOTICE @@ -24,6 +24,31 @@ https://github.com/MAX-API-Next/MAX-API Modified versions must not misrepresent the origin of the software and must mark their changes in accordance with AGPLv3 Section 7(c). +==== Preserved New API Upstream Notice ==== + +new-api +Copyright (c) QuantumNous and contributors. + +This project includes software derived from New API, which is licensed under +the GNU Affero General Public License v3.0. The following additional terms from +the New API NOTICE are preserved: + +Pursuant to Section 7(b) of the GNU Affero General Public License version 3, +the following reasonable legal notice and author attribution must be preserved +by modified versions in the Appropriate Legal Notices and in any prominent +about, legal, footer, or attribution location presented by the user interface: + +"Frontend design and development by New API contributors." + +Modified versions that present a user interface must also preserve a visible +link to the original project in a prominent about, legal, footer, or +attribution location: + +https://github.com/QuantumNous/new-api + +Modified versions must not misrepresent the origin of the software and must +mark their changes in accordance with AGPLv3 Section 7(c). + ==== Third-Party Notices ==== This product includes third-party open source software. Copyright notices and diff --git a/README.en.md b/README.en.md index 67e8ad3a..0b69f8b8 100644 --- a/README.en.md +++ b/README.en.md @@ -1,10 +1,14 @@ -
+# MAX API -![max-api](/web/default/public/logo.png) +
-# MAX API +![MAX API](./web/default/public/logo.png) + +**AI Models and Agents governance, intelligent operations, and open collaboration infrastructure for the AGI application era** + +**MAX API 2.0: entering the intelligent operations era · evolving from a unified model gateway to AGI-native governance and operations** -🍥 **AI Model Governance, AgentOps, and AGI Application Service Infrastructure** +[View the MAX API 2.0 Preview release notes](https://github.com/MAX-API-Next/MAX-API/releases/tag/v2.0.0-smartops.pre1)

简体中文 | @@ -30,736 +34,319 @@

- Positioning • - Release Channels • - Governance • - Use Cases • - Quick Start • - Capabilities • - Configuration • - Architecture • - Models & APIs • - Deployment • - FAQ • - License + ⭐ Star the project • + 💬 Join the community • + 📚 Documentation • + 🚀 Releases

-
- ---- - -## 📝 Project Description - -MAX API is an AI model governance, AgentOps, and application service infrastructure project initiated, maintained, and operated long term by AGI enthusiasts from research institutions and universities. It provides developers, researchers, teams, and organizations with a stable and reusable service layer. The project focuses on the operational problems that appear after AI applications move into real use: more models, frequent upstream API changes, longer Agent call chains, and rising pressure around cost and auditability. MAX API provides a unified access, authentication, routing, billing, observability, and governance layer between applications, Agents, users, organizations, and upstream model providers, helping AI applications run with greater stability and control. - -In practice, MAX API is more than a request forwarder. It is an operable gateway for AI-ready applications and Agent workloads, bringing protocol normalization, provider differences, traffic bursts, long streaming responses, large request bodies, multi-node cache, cost audit, and performance observability under one governance boundary. - -Ongoing investment areas: - -- **AI model governance**: continuously tracks model updates, API changes, parameter differences, pricing rules, and task protocols across OpenAI, Azure OpenAI, AWS Bedrock, Vertex AI, Ollama, and domestic platforms such as DeepSeek, Qwen / Alibaba Cloud Model Studio, Zhipu GLM, Kimi, Doubao / Volcano Engine, Tencent Hunyuan, Baidu ERNIE / Qianfan, iFlytek Spark, MiniMax, 01.AI, and SiliconFlow. It also tracks application and multimodal ecosystems such as Dify, RAGFlow, Kling, and Seedance, bringing distributed model capabilities into unified governance through channels, model mapping, protocol conversion, path overrides, and configurable task protocols. -- **AI Agent governance / AgentOps**: improves token governance, model access control, call tracing, cost attribution, failure diagnosis, and log audit around Agent, workflow, and tool-calling scenarios, while reserving unified governance boundaries for MCP-style tools and services. -- **Channel configuration governance**: provides a channel capability matrix and configuration validation in channel creation and editing views, showing capabilities such as `chat/completions`, `responses`, `embeddings`, `rerank`, `video tasks`, and model discovery, while warning about common risks such as Base URL, JSON configuration, Vertex AI region, Codex credentials, and video task placeholders. -- **Operations and cost governance**: continuously improves channel routing, retry, rate limiting, pre-charge, failure refund, log observability, cost statistics, and operations analysis. Text and multimodal token scenarios can use expression-based billing and unified JSON configuration, while asynchronous video tasks can use parameterized rate-cards, making model and Agent costs easier to understand, calculate, and maintain in batches. - -> [!IMPORTANT] -> - When providing public generative AI services, users should comply with applicable regulatory requirements and independently complete filings, licensing, content safety, real-name verification, log retention, tax, payment, and upstream authorization obligations required by their jurisdiction. -> - Sensitive capabilities such as log audit and content retention should only be enabled when there is a lawful basis, clear notice, permission isolation, and proper data security measures. -> - MAX API provides a gateway governance layer for model and Agent workloads. It does not provide upstream model accounts, API keys, foundation model training, or replace Agent orchestration/application frameworks such as Dify, LangChain, or MCP Server. - ---- - -## 🚦 Release Channels - -Current MAX API releases are divided into stable releases and Preview releases. Preview releases make new capabilities and fixes available early so the community and deployment operators can validate compatibility, stability, and security in real environments. A stable release is published after the corresponding Preview release has run stably for 1 week, reducing production upgrade risk and improving system safety and reliability. - -Production deployments should prefer stable releases. Use Preview releases in test or canary environments when you need to validate new features, fixes, or compatibility changes early, and prepare database backups and rollback plans before upgrading. - ---- - -## 🎯 Project Positioning - -In the AGI application era, MAX API focuses on open AI model governance and AI Agent governance infrastructure, building the service, governance, and operations layer that helps developers and organizations run AI applications and Agent workloads reliably: - -- **Model governance plane**: unified management for model entry points, channels, providers, protocol formats, model mappings, pricing rules, task protocols, and multimodal APIs. -- **AgentOps control plane**: does not replace Agent orchestration frameworks; instead it provides token governance, model access control, call logs, cost tracking, failure diagnosis, and operations analysis at the gateway layer. -- **Channel configuration plane**: reduces misconfiguration risk when adding upstream channels, migrating providers, or maintaining non-standard APIs through capability matrices, form validation, model discovery, and protocol templates. -- **Protocol and provider adaptation layer**: continuously tracks official overseas APIs, domestic model platform APIs, and OpenAI-compatible / non-standard interface changes, then normalizes them into stable application-side APIs. -- **Cost, quota, and reliability governance**: supports channel routing, weighted distribution, retry, rate limiting, pre-charge, failure refund, expression billing, fixed pricing, task rate-cards, multiplier billing, and usage statistics. -- **Performance and scalability governance**: uses Redis / in-memory cache, model request rate limits, streaming timeouts and large-response buffers, request body limits, disk cache, Pyroscope profiling, and graceful shutdown to support stable single-node and multi-node deployments. -- **Organization operations and audit layer**: provides user management, group management, private deployment, data retention, audit, and continuous operations optimization for teams, research institutions, enterprises, and community services. -- **Reusable governance templates**: accumulates channel templates, task protocol templates, pricing configuration, deployment practices, and operations experience to reduce onboarding cost for new models, providers, and Agent scenarios. - ---- - -## 🧠 Governance Framework - -MAX API brings AI model and AI Agent execution into a configurable, observable, accountable, and auditable governance framework. - -| Governance object | MAX API capabilities | Goal | -|----------|-------------------|------| -| Model assets | Model lists, model mapping, model groups, model restrictions, pricing rules, and multimodal API management | Help organizations know which models exist, who can use them, how they are billed, and how to switch them | -| Upstream channels | Provider channels, weights, groups, status, keys, Base URL, path overrides, capability matrix, configuration validation, model discovery, and failure retry | Reduce risks from single-provider outages, price changes, rate limits, misconfiguration, or API changes | -| Protocol formats | OpenAI Compatible, Responses, Claude Messages, Gemini, Realtime, generic video task protocol, and protocol conversion | Let applications face stable interfaces instead of directly handling provider-specific protocol differences | -| Agent tokens | API keys, token groups, model scopes, quota limits, expiration, and access control | Assign independent, revocable, and quota-limited credentials to Agents, workflows, and tool calls | -| Usage and cost | Request logs, usage statistics, expression billing, tiered billing JSON, task rate-cards, pre-charge, and failure refund | Attribute model costs to users, groups, tokens, models, channels, and nodes | -| Asynchronous tasks | Video task submission, polling, status mapping, result proxying, and task billing | Govern long-running, multi-state, multi-provider multimodal tasks uniformly | -| Audit and security | Admin-side log audit, error logs, request limits, streaming timeout, login, and permission control | Provide controlled audit boundaries in private deployment and compliance scenarios; sensitive content audit is managed under Security & Limits | -| Organization operations | Users, groups, balance, payment, system settings, dashboards, and operations configuration | Support continuous operations for teams, research institutions, enterprises, or community services | - ---- - -## 🧩 Use Cases - -- **Internal AI model governance platform**: centrally manage users, tokens, models, channels, groups, permissions, pricing, and billing so each team does not repeatedly integrate and maintain upstream services. -- **Runtime and governance base for Agent applications**: provide a stable model gateway, token isolation, cost control, call observability, failure diagnosis, and audit foundation for Agents, workflows, and tool-calling applications. -- **Domestic model and multi-provider adaptation center**: continuously track domestic and overseas model platform APIs and pricing changes, reducing adaptation cost through channel configuration, model mapping, path overrides, and protocol templates. -- **Multimodal task governance platform**: unify access to text, images, videos, audio, embeddings, rerank, and realtime conversation APIs, with status, result proxying, and billing governance for asynchronous tasks. -- **Model and Agent cost accounting platform**: allocate quotas, calculate fees, summarize bills, and analyze costs by user, token, model, channel, and group. -- **Private and compliance-oriented operations environment**: suitable for teams or organizations that need to independently manage keys, data, permissions, logs, audit, and billing strategies. - ---- - -## 🚀 Quick Start - -SQLite is used by default, so local evaluation does not require an external database. - -> [!WARNING] -> SQLite is intended only for local evaluation, development, and small-scale testing. It is not recommended for production: concurrent requests, multi-instance deployments, large log or usage datasets, database migrations, backup and restore operations, and long transactions can cause lock contention, blocked writes, slow or failed migrations, and other availability or data-maintenance problems. Use MySQL ≥ 5.7.8 or PostgreSQL ≥ 9.6 with a reliable backup and recovery plan in production. - -```bash -# 1. Pull the image -docker pull cscitechtop/max-api:latest - -# 2. Start the service and persist data under ./data -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest - -# 3. Open the console -# Visit http://localhost:3000 in your browser -``` - -Production deployment should use Docker Compose and explicitly configure the database, Redis, session secret, encryption secret, and log directory. - -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API - -# Modify database, Redis passwords, and environment variables in docker-compose.yml as needed -docker compose up -d -``` - -> [!WARNING] -> If you operate this project as a public generative AI service or API service, complete upstream authorization, filing, content safety, real-name verification, log retention, tax, payment, and user agreement obligations first. - ---- - -## ✨ Key Capabilities - -### AI Model Governance - -| Capability | Description | -|------|------| -| Unified model entry point | Supports OpenAI-compatible APIs, Responses, Claude Messages, Gemini, Realtime, and other protocol entries so applications can access models through one gateway | -| Multi-provider model pool | Supports OpenAI, Azure, Claude, Gemini, AWS Bedrock, Vertex AI, and Ollama; continuously tracks and includes adapters or compatible access for DeepSeek, Qwen, Zhipu GLM, Kimi, Doubao, Tencent Hunyuan, ERNIE, iFlytek Spark, MiniMax, 01.AI, SiliconFlow, and other domestic platforms | -| Upstream ecosystem adaptation | Supports governance for interfaces related to Codex, Dify, RAGFlow, Kling, Seedance, and other application, Agent, and multimodal platforms, bringing model calls, workflow calls, and asynchronous tasks into one gateway | -| Model mapping and access scope | Supports per-channel model lists, model mapping, user groups, token groups, and model restrictions, allowing different teams, applications, or Agents to use different model sets | -| Channel capability matrix | Channel editing view shows capability status for `chat/completions`, `responses`, `Claude Messages`, `Gemini native`, `embeddings`, `images`, `audio`, `rerank`, `video tasks`, `model discovery`, and more | -| Channel configuration validation | Checks API Key, model list, Base URL, extra configuration, JSON objects, Vertex AI region, Codex credentials, model discovery capability, and video task path placeholders before saving | -| Multimodal model governance | Supports chat, images, video, audio, embeddings, rerank, realtime conversation, and submission/polling/status mapping/result proxying for asynchronous video tasks | -| Generic video task protocol | Allows task submission, query, progress, status mapping, error message, and result URL paths from different video upstreams to be configured uniformly in a channel; request-body passthrough and rewrites use the existing channel settings; default paths are `/v1/videos/create` and `/v1/videos/{task_id}` | -| Protocol conversion and custom upstreams | Supports conversion and adaptation among OpenAI Compatible, Responses, Chat Completions, Claude Messages, Gemini, and other formats, as well as legally authorized upstream URLs, path overrides, and task protocol parsing rules | - -### AI Agent Governance / AgentOps - -| Capability | Description | -|------|------| -| Agent token isolation | Create independent API keys for Agents, workflows, plugins, tool calls, or users, with model scope, quota, expiration, and group settings | -| Model access control | Control which models an Agent can call, which channels it can use, and how much quota it can consume through users, tokens, groups, model restrictions, and channel policies | -| Call-chain observability | Provides request logs, usage statistics, channel hits, latency, errors, and retry information to diagnose Agent failures, cost anomalies, and upstream instability | -| Cost attribution | Tracks cost and usage by model, channel, user, group, token, and node, making it easier to calculate costs for different Agents, business lines, or deployment nodes | -| Admin audit | Private deployments can enable admin-side log audit according to compliance requirements; normal user log APIs filter admin-only audit fields | -| Operations dashboard | Provides admin-facing analytics, user management, channel management, system settings, and operations analysis | - -### Cost, Billing, and Reliability Governance - -**Model pricing expressions** - -- **One expression = the complete pricing rule for one token model**: tiered pricing, cache hits, image/audio token items, time-based discounts, and dynamic markups based on request headers or parameters can all be written in one line. -- **Prices are real prices**: coefficients can be entered directly as USD per million tokens. `p * 2.5` means USD 2.5 per million input tokens. Traditional multiplier mode remains compatible. -- **Visual + raw editing modes**: fill in prices and conditions visually or edit expressions directly, with built-in templates for common models. -- **Unified JSON batch maintenance**: maintain `{ enabled, expr }` rules for multiple models in one `Tiered billing JSON` window; saving atomically updates `billing_mode` and `billing_expr`. -- **Automatic token normalization**: separates cache, image, audio, and other subcategories from input/output according to upstream format and variables used by the expression, preventing double billing; logs can show the matched pricing tier and details. - -**Task billing, traditional billing, and reliability** - -- Supports parameterized rate-card billing for asynchronous tasks such as video, matching prices by model, vendor, duration, quality, audio, video input, and other fields. `task_billing_setting.rate_cards` can be maintained as JSON and split by `vendor` for providers such as Sora, Veo, Seedance, and Kling. -- Compatible with usage-based, per-call, cache-hit, model multiplier, group multiplier, and channel multiplier billing modes. -- Supports pre-charge, failure refund, exception handling, and consumption logs for long-running Agent call chains and asynchronous multimodal tasks. -- Supports weighted channel routing, failure retry, disabled-channel bypass, and model-level routing to reduce upstream impact on applications and Agents. -- Supports Redis and in-memory cache for single-node and multi-node deployments. - -### Performance and Scalability Governance - -| Capability | Description | -|------|------| -| Cache and multi-node scaling | Single-node deployments can use in-memory cache, while multi-node deployments can use Redis; user, token, channel affinity, and quota-related caches reduce repeated database reads, while `SESSION_SECRET`, `CRYPTO_SECRET`, and `NODE_NAME` keep sessions, encryption, and log attribution consistent | -| Rate limits and capacity protection | Supports global API / Web rate limits, critical endpoint limits, search limits, model request limits, and group-specific model request quotas; counters can use Redis or memory | -| Streaming and large-request controls | Supports `STREAMING_TIMEOUT`, `STREAM_SCANNER_MAX_BUFFER_MB`, `MAX_REQUEST_BODY_MB`, `MAX_FILE_DOWNLOAD_MB`, and related settings for long streams, large SSE lines, decompressed request bodies, and remote file downloads | -| Relay connection tuning | Supports `RELAY_TIMEOUT`, `RELAY_IDLE_CONN_TIMEOUT`, `RELAY_MAX_IDLE_CONNS`, and `RELAY_MAX_IDLE_CONNS_PER_HOST` for upstream HTTP timeout and connection-pool behavior | -| Disk cache and performance observability | System performance settings can enable disk cache for large request bodies and configure cache threshold and capacity; operations endpoints can inspect / clear disk cache, and Pyroscope can collect CPU, memory, goroutine, mutex, and block profiles | -| Graceful shutdown and data flush | Shutdown supports `SHUTDOWN_TIMEOUT_SECONDS` and `QUOTA_DATA_CACHE_SAVE_TIMEOUT_SECONDS` so the process can close HTTP handling and save quota cache before exit when possible | - -### Security and Organization Management - -- Supports JWT, WebAuthn/Passkeys, OAuth, OIDC, Telegram, Discord, LinuxDO, and other login methods. -- Supports administrator, normal user, group, token, and model access control. -- Supports request body size limits, streaming timeout control, error logs, and runtime health checks. -- Supports unified session secret, encryption secret, and Redis shared cache for multi-node deployments. - ---- - -## 🆚 Why Use a Gateway +

+ Community • + Quick start • + Why MAX API • + AGI direction • + Capabilities • + SmartOps • + Preview deployment +

-| Dimension | Direct official SDK / API integration | Through MAX API gateway | -|------|------------------------|-------------------| -| Model access | One SDK, authentication flow, and parameter set per provider | One model entry point, one integration, multi-model reuse | -| Model governance | Model lists, pricing, permissions, and channels scattered across platforms | Unified model, channel, mapping, group, quota, and pricing rule management | -| Agent access | Agents directly hold upstream keys, making revocation and quota control difficult | Assign independent tokens to Agents with model, quota, expiration, and group limits | -| Protocol differences | Applications adapt Claude, Gemini, Responses, and other formats themselves | Gateway handles protocol conversion and provider adaptation | -| Failure handling | Applications implement retry, fallback, and error normalization themselves | Channel failure retry, weighted routing, and error handling are built in | -| Performance and scaling | Applications handle timeouts, rate limits, connection pools, and cache themselves | Gateway centralizes streaming timeouts, request limits, Redis / in-memory cache, connection-pool tuning, and performance observability | -| Cost statistics | Bills are scattered across providers and hard to attribute by user or Agent | Unified quota, billing, usage statistics, and consumption logs, attributable by token and model | -| Audit boundary | Application-side logging is fragmented and retention/permission policies differ | Unified admin audit entry with normal user logs filtering admin-only fields | -| Private deployment | Keys, logs, and billing strategies are scattered | Self-hosted control over keys, data, logs, and policies | +
--- -## 🧭 Architecture Overview - -MAX API uses a layered architecture. Application, SDK, or Agent requests enter through a unified entry point, pass through routing, middleware, controllers, and business services, and are finally adapted by the relay layer to the corresponding upstream provider. The data and cache layers provide persistence and acceleration for model governance, Agent token governance, billing, logs, audit, and task status. - -```mermaid -flowchart LR - Client[Client / SDK / Agent] --> Router[Router
Routing] - Router --> MW[Middleware
Auth · Rate Limit · Dispatch · Logs] - MW --> Ctrl[Controller
Request Handlers] - Ctrl --> Svc[Service
Model Governance · AgentOps · Billing Audit] - Svc --> Relay[Relay
Proxy / Protocol Conversion] - Relay --> Adapters[Channel Adapters
OpenAI · Claude · Gemini · Domestic Platforms · Custom Upstreams] - Adapters --> Upstream[(Upstream Model Services)] - Svc --> Model[Model
GORM] - Model --> DB[(SQLite · MySQL · PostgreSQL)] - Svc --> Cache[(Redis · In-memory Cache)] -``` - -### Directory Structure - -| Directory | Responsibility | -|------|------| -| `router/` | HTTP routing, including API, relay, dashboard, and web entries | -| `controller/` | Request handlers for parameter parsing, authenticated business entry points, and response wrapping | -| `service/` | Business logic including model governance, AgentOps, logs, billing, audit, tasks, channels, and system settings | -| `model/` | Data models and database access, based on GORM and compatible with SQLite, MySQL, and PostgreSQL | -| `relay/` | AI API relay, protocol conversion, and provider adaptation | -| `relay/channel/` | Provider adapters such as openai, claude, gemini, aws, and more | -| `middleware/` | Authentication, rate limiting, CORS, logs, request distribution, and context handling | -| `setting/` | Model pricing, task billing, operations, system, security, and performance settings | -| `common/` | Shared utilities for JSON, encryption, Redis, rate limiting, environment variables, and more | -| `dto/` / `types/` | Type definitions for requests, responses, errors, and relay formats | -| `constant/` | API types, channel types, context keys, and other constants | -| `i18n/` / `oauth/` / `pkg/` | Backend i18n, OAuth implementations, and internal packages | -| `web/` | Frontend theme container; the default theme is under `web/default/` | - -### Technology Stack - -| Layer | Technology | -|------|------| -| Backend | Go 1.25+, Gin, GORM v2 | -| Frontend | React 19, TypeScript, Rsbuild, Base UI, Tailwind CSS | -| Package management | Bun workspace | -| Database | SQLite / MySQL ≥ 5.7.8 / PostgreSQL ≥ 9.6 | -| Cache | Redis + in-memory cache | -| Authentication | JWT, WebAuthn/Passkeys, OAuth, OIDC | +MAX API sits between applications, Agents, and upstream model services as a unified model gateway, governance control plane, and operations entry point. The MAX-API-Next community builds the project around practical AGI engineering and welcomes developers, researchers, enterprise engineering teams, university technology enthusiasts, and open-source contributors. Our goal is to provide the model access, permissions, cost controls, Evidence, intelligent operations, and safety foundations that real AGI applications require. ---- +In the AGI field, we will **continuously deliver advanced and verifiable technology, turn real production problems into open engineering capabilities, and build a community for shared research and contribution.** -## 🤖 AI Model and Interface Support +## 🌐 Join the MAX-API-Next community -> Actual available models depend on your upstream authorization, channel configuration, model mapping, and provider support. MAX API focuses on bringing these capabilities into unified governance; it does not provide upstream model services itself. +MAX API is more than a code repository. It is a long-term open collaboration around AI Models, Agents, AgentOps, and AGI engineering. Whether you operate a model gateway, build Agents, adapt new models, research evaluation and governance, or improve documentation and localization, you are welcome to join the community and contribute. -| Type | Description | -|------|------| -| OpenAI-Compatible | Compatible APIs such as Chat Completions, Embeddings, Images, and Audio, usable as a general model entry point for most applications and Agents | -| OpenAI Responses | Responses-format requests, relay, and Responses ↔ Chat Completions compatibility conversion for gradually adopting newer OpenAI application protocols | -| Claude Messages | Conversion between Claude Messages and OpenAI-compatible formats to reduce multi-protocol maintenance on the application side | -| Google Gemini | Gemini chat, text, and `/v1/responses` compatibility conversion | -| Azure OpenAI | Azure OpenAI and Realtime related APIs | -| AWS Bedrock | Bedrock Runtime model access | -| Upstream platforms and application ecosystem | AWS, Azure, Vertex, Ollama, Codex, Dify, RAGFlow, Kling, Seedance, and similar platforms or applications can be governed according to channel capabilities | -| Domestic models and platforms | Built-in adapters or compatible access for DeepSeek, Qwen / Alibaba Cloud Model Studio, Zhipu GLM, Kimi, Doubao / Volcano Engine, Tencent Hunyuan, Baidu ERNIE / Qianfan, iFlytek Spark, MiniMax, 01.AI, SiliconFlow, and more | -| `rerank` | Reranking models such as Cohere and Jina for retrieval augmentation and Agent retrieval chains | -| Midjourney / Suno / Dify | Adapters for image, music, workflow, and related services | -| Video task APIs | Supports submission, body passthrough or parameter overrides, polling, status mapping, result proxying, and parameterized billing for video generation tasks such as `/v1/videos/create` and `/v1/videos/{task_id}` | -| Custom upstreams | Supports legally authorized upstream URLs, protocol adaptation rules, Responses / Chat conversion, path overrides, status mapping, error message paths, and task result parsing | +**Join the community to follow releases, model and protocol changes, deployment practices, troubleshooting knowledge, and opportunities to build together.** -### Main Supported Interfaces +

+ QQ group: 950126533 • + WeChat group: search for MAX-API +

-
-View interface categories - -- Chat: `/v1/chat/completions` -- Responses: `/v1/responses` -- Images: `/v1/images/*` -- Audio: `/v1/audio/*` -- Video: `/v1/videos/*` -- Embeddings: `/v1/embeddings` -- Rerank: `/v1/rerank` -- Realtime conversation: OpenAI Realtime-compatible APIs -- Claude Messages: Claude native-format entry -- Gemini: Google Gemini format entry +| Community entry | Purpose | +|---|---| +| [MAX-API-Next on GitHub](https://github.com/MAX-API-Next) | Follow community projects, technical direction, and open collaboration | +| [MAX API Issues](https://github.com/MAX-API-Next/MAX-API/issues) | Report reproducible problems, propose improvements, and share compatibility changes | +| [MAX API Releases](https://github.com/MAX-API-Next/MAX-API/releases) | Follow stable and Preview releases | +| [Ask DeepWiki](https://deepwiki.com/MAX-API-Next/MAX-API) | Search and understand the codebase quickly | +| Technical and ecosystem cooperation | Contact `maxapi@max-api.ai` | -
+### Contributors we are looking for -### Reasoning Effort Support +- **Model and protocol contributors**: adapt new models, providers, Reasoning behavior, tool calling, and multimodal task protocols. +- **Agent and application developers**: share integration and governance practices for Dify, RAGFlow, Codex, MCP, workflows, and research Agents. +- **Reliability and security engineers**: strengthen cross-database tests, asynchronous task recovery, settlement safety, cache consistency, and permission boundaries. +- **Documentation and community contributors**: improve deployment guides, FAQs, examples, translations, reproducible experiments, and contributor onboarding. +- **Researchers and evaluation developers**: help build Evidence, Evaluators, Detectors, Runbooks, and controlled-autonomy designs.
-View example model names - -**OpenAI series:** +View collaboration areas, principles, and ways to participate -- `o3-mini-high` -- `o3-mini-medium` -- `o3-mini-low` -- `gpt-5-high` -- `gpt-5-medium` -- `gpt-5-low` +| Collaboration area | Example contributions | +|---|---| +| Model and provider ecosystem | Model/protocol adapters, compatibility tests, model-list and deprecation changes, channel templates | +| AgentOps and AGI application governance | Agent integration examples, token and permission boundaries, cost governance, operational practices | +| SmartOps and Evidence | Sanitized incident samples, metric definitions, alert rules, data-quality notes, diagnosis and evaluation methods | +| Reliability, billing, and security | Idempotent settlement, asynchronous recovery, cross-database regression tests, cache consistency, high-risk operation verification | +| Documentation, tutorials, and localization | Deployment tutorials, architecture docs, FAQs, case studies, translations, contributor guides | -**Claude thinking models:** +Please provide a minimal reproduction, version, environment, sanitized logs, or test evidence whenever possible. Protocol, database, and user-contract changes should document compatibility, migration, and rollback paths. Do not submit real API keys, customer data, raw payment records, private logs, or unauthorized data. Contributions involving money, security, credentials, production data, or automated execution require stricter testing, independent review, and a clearly accountable owner. -- `claude-3-7-sonnet-20250219-thinking` +You can start by: -**Gemini series:** - -- `gemini-2.5-flash-thinking` -- `gemini-2.5-flash-nothinking` -- `gemini-2.5-pro-thinking` -- `gemini-2.5-pro-thinking-128` -- You can also append `-low`, `-medium`, or `-high` to Gemini model names to control reasoning effort. +1. Reporting a reproducible problem, protocol difference, or model compatibility change. +2. Adding a failing test, cross-database case, frontend regression, or sanitized Evidence to an existing issue. +3. Improving model/channel configuration, deployment instructions, FAQs, architecture documentation, or translations. +4. Sharing sanitized Agent integration, cost governance, SmartOps, or private deployment practices. +5. Proposing an Evaluator, Detector, Runbook, or controlled-autonomy design with explicit capability and risk boundaries.
---- - -## 🔧 Governance Configuration - -### Recommended Initial Governance Setup - -1. After deployment, enter the console and create or confirm the administrator account. -2. Configure system settings, user registration policy, login methods, and security limits. -3. Add upstream channels and fill in legally authorized API keys, Base URL, model lists, model mappings, and channel settings. -4. Configure user groups, token groups, model restrictions, quota policies, and pricing rules according to your organization structure. -5. Create independent tokens for applications, Agents, or workflows, and configure model scope and quotas by business line, environment, or risk level. -6. Configure failure retry, log recording, cache strategy, and consumption statistics in operations settings. -7. If admin-side content audit is needed, enable it under "System Settings → Security & Limits → Log Audit" under proper compliance conditions, and ensure "Record quota usage (Log Maintenance)" is enabled. - -### Channel Capability Matrix and Configuration Validation - -When creating or editing a channel, the system displays a capability matrix and realtime validation results according to the channel type. Interface names in the matrix keep their original technical wording, such as `chat/completions`, `responses`, `embeddings`, `rerank`, and `video tasks`, while descriptions explain what the channel can handle. - -Validation covers common issues including: - -- Missing API Key for new channels, empty model list, or missing Base URL / extra configuration when required. -- Base URL incorrectly ending with `/v1`, causing the system to append upstream paths again. -- `setting`, `param_override`, `header_override`, `settings`, and similar fields are not JSON objects. -- Vertex AI region lacks `default`, or service account key is not valid JSON. -- Codex channel credentials lack `access_token` or `account_id`. -- Model discovery or automatic sync is enabled on a channel that does not support discovery. -- Video task query path lacks one of `{task_id}`, `{operation_name}`, or `{upstream_task_id}`. - -### Generic Video Task Protocol - -Video model providers often differ in paths, task IDs, status fields, progress fields, error fields, and result URL fields. MAX API extends the task protocol capability from a single-model feature into a generic video task protocol for OpenAI, Ali, Gemini, MiniMax, Vertex AI, VolcEngine, Kling, Jimeng, Vidu, Doubao Video, Sora, and other video task channels. - -Supported configuration levels: - -- **Path override only**: configure only `submit_path` and `query_path`; the system still uses the official response parser of the corresponding channel. This is suitable for compatible channels that only change upstream paths. -- **Full protocol parsing**: set `task_protocol = "generic_video_task"` and configure paths for task ID, status, progress, result URL, error message, and status mapping. This is suitable for non-standard video task responses. -- **Request-body handling**: the generic video task protocol no longer defines a separate request-body generation mode. Use the channel-level `Pass Through Body` setting to forward client JSON as-is, and use the existing `Param Override` feature for field rewrites, defaults, or header coordination. - -Default task paths: - -```json -{ - "task_protocol": "generic_video_task", - "task_protocol_config": { - "submit_path": "/v1/videos/create", - "query_path": "/v1/videos/{task_id}", - "task_id_path": "task_id", - "status_path": "status", - "progress_path": "progress", - "result_url_paths": [ - "result.primary_url", - "result.urls.0", - "data.result.primary_url", - "url", - "video_url", - "download_url" - ], - "error_message_path": "error_message", - "status_map": { - "queued": "QUEUED", - "running": "IN_PROGRESS", - "succeeded": "SUCCESS", - "failed": "FAILURE" - } - } -} -``` - -Query paths support `{task_id}`, `{operation_name}`, and `{upstream_task_id}`. `{operation_name}` can preserve multi-segment path values, which is suitable for Gemini / Vertex-style operation query APIs. Video content can be read through `/v1/videos/{task_id}/content`; when you need to hide upstream resource domains, let end users access this content proxy URL and combine it with authentication, SSRF protection, and allowed port configuration. - -### Billing JSON Maintenance - -Model billing in system settings supports two unified JSON maintenance entries: +Companion documentation: [MAX-API-Docs](https://github.com/MAX-API-Next/MAX-API-Docs) (deployment, configuration, and usage guides). -- **Tiered billing JSON**: maintain `{ enabled, expr }` configuration for multiple models in one `Tiered billing JSON` window; saving updates `billing_mode` and `billing_expr` together. -- **Task rate-card JSON**: maintain asynchronous task billing rules through `task_billing_setting.rate_cards`, with `vendor` partitions for video models such as Sora, Veo, Seedance, and Kling. +Model providers, Agent/workflow projects, open-source communities, researchers, and enterprise engineering teams are welcome to collaborate. Formal partnerships, joint announcements, or use of an institution's name require explicit authorization from both parties. -Video models such as Seedance 2.0 can use request parameters such as resolution and video input in multiplier or rate-card billing. When using passthrough or parameter overrides, keep the final upstream request fields aligned with the billing fields. +> [!IMPORTANT] +> When offering generative AI services to the public, operators are responsible for upstream authorization, registration or licensing, content safety, identity verification, log retention, taxation, payments, user agreements, and any other obligations required in their jurisdiction. Enable log auditing and content retention only with a lawful basis, clear notice, permission isolation, and appropriate data-security controls. -Example structure: +MAX API administration console -```json -{ - "model-name": { - "enabled": true, - "expr": "len <= 200000 ? tier(\"standard\", p * 3 + c * 15) : tier(\"long_context\", p * 6 + c * 22.5)" - } -} -``` +## 🧠 Technical direction for AGI -A task rate-card can match prices by request parameters: - -```json -{ - "vendor/model-name": { - "vendor": "kling", - "unit": "second", - "quantity_field": "duration", - "default_quantity": 5, - "strict": true, - "defaults": { - "quality": "std", - "has_audio": "false" - }, - "rows": [ - { - "id": "std_no_audio", - "match": { - "quality": "std", - "has_audio": "false" - }, - "unit_price": 0.6 - } - ] - } -} -``` +AGI applications will not depend forever on one model, one protocol, or one-shot requests. They require cross-model reasoning, tool use, multimodal tasks, long-running execution, cost constraints, production Evidence, and recoverable failure handling. MAX API starts from these verifiable engineering problems to build an AI Models and Agents governance foundation. -### Common Operations Entries +| Technical direction | Current foundation | Value for AGI applications | +|---|---|---| +| Multi-model and multi-protocol access | OpenAI-Compatible APIs, Responses, Claude Messages, Gemini, Realtime, multimodal and asynchronous task protocols | Gives applications and Agents a relatively stable entry point while the model ecosystem continues to change | +| Reasoning and tool-context compatibility | Reasoning Effort, tool definitions, Tool Calls, tool-response association, and multi-turn context conversion | Reduces loss of reasoning information and tool semantics when switching providers | +| Governance control plane | Users, tokens, model scopes, groups, routing, rate limits, quotas, pricing, and administrator permissions | Creates separate identity, access, and budget boundaries for different Agents, environments, and tasks | +| Recoverable billing and task lifecycle | Pre-charge, final settlement, idempotent records, failed-task refunds, asynchronous polling, and manual reconciliation states | Prevents duplicate charges, incorrect refunds, and untraceable results during long tasks, retries, and failure windows | +| Evidence and intelligent operations | Logs, errors, retries, performance buckets, active alerts, channel/model performance, and settlement evidence | Grounds diagnosis, evaluation, and future Agent recommendations in traceable facts rather than prompt-only inference | +| Security and organization governance | Passkeys, 2FA, scoped re-verification, session revocation, audit, and rate limits for sensitive operations | Preserves explicit accountability around high-risk configuration, credentials, and operations | +| Controlled autonomy and engineering evolution | **Long-term blueprint**: Policy, Budget, Approval, Shadow, Canary, Rollback, and isolated Coding Workspaces | Requires automation to be evaluated, constrained, and audited before it can enter low-risk production actions | -| Feature | Description | -|------|------| -| Channel management | Configure upstream providers, model mappings, channel weights, keys, protocol paths, and status, while using capability matrix and validation to catch risks early | -| Models and pricing | Maintain model lists, model prices, expression billing, tiered billing JSON, task rate-card JSON, and model display information | -| Token management | Create access tokens for applications, Agents, workflows, tool calls, or users and restrict models and quota | -| User management | Manage users, groups, balance, permissions, and status | -| Usage logs | View call records, consumption, latency, errors, channel hits, and admin-visible audit information | -| System settings | Manage security limits, log audit, model pricing, task billing, operations strategy, log maintenance, payment, and site settings | -| Dashboard | View total requests, model usage, consumption trends, channel status, and Agent token costs | +### Technical principles ---- +- **Evidence before Action**: establish verifiable facts before diagnosis, recommendations, or automated actions. +- **Governance before Autonomy**: identity, permissions, budgets, approval, audit, and rollback must precede autonomous capabilities. +- **One Billing Truth**: production billing, quota, and settlement keep a single source of truth; Agents and plugins do not create a second accounting system. +- **Compatibility by Design**: continue to support SQLite, MySQL, PostgreSQL, multiple provider protocols, and portable application contracts. +- **Open Collaboration, Safe Boundaries**: open protocol adapters, tests, documentation, evaluations, and governance designs while keeping high-risk production, financial, credential, and release actions under explicit approval. -## 🚢 Deployment +### MAX API 2.0 technical highlights -### Requirements +- **Evidence-driven SmartOps**: brings resource alerts, channel/model performance, data-quality states, and billing-settlement evidence into one operations entry point while preserving the boundary between human review and real financial state. +- **Continuous support for advanced model protocols**: improves Reasoning, cache keys, penalty parameters, tool definitions, and multi-turn Tool Context compatibility across Responses, Claude Messages, Gemini, and Ollama. +- **Recoverable billing and asynchronous task semantics**: uses idempotent settlement, durable effects, task IDs, and explicit pending/manual states to prevent retries from causing duplicate charges, incorrect refunds, or lost tasks. +- **Scoped re-verification for high-risk operations**: Passkeys, 2FA, Telegram, API Tokens, and session revocation use scope-bound step-up verification, while `session_generation` invalidates old sessions promptly. +- **Cross-database support and continuous verification**: core data paths support SQLite, MySQL, and PostgreSQL; Go tests, frontend Bun tests, TypeScript type checks, JSON-wrapper rules, and synchronized test mirrors form the release gate. -| Component | Requirement | -|------|------| -| Container engine | Docker / Docker Compose | -| Local database | SQLite, only for local evaluation, development, or small-scale testing; mount `/data` when using Docker | -| Production database | MySQL ≥ 5.7.8 or PostgreSQL ≥ 9.6 with a reliable backup and recovery plan | -| Cache | In-memory cache for single-node deployments; Redis recommended for multi-node deployments | -| Frontend build | Bun workspace; keep `web/package.json` and `web/bun.lock` | -| Source build | Use the Go version declared in `go.mod` (currently Go 1.25.1+) with the repository `go.sum`; after dependency or security updates, run `go mod download`, `go mod verify`, and rebuild | +## 💡 Why MAX API -### Recommended Environment Variables +| Dimension | Connecting directly to multiple providers | Using MAX API | +|---|---|---| +| Application integration | Maintain separate SDKs, protocols, authentication, and error formats | Use a relatively stable application-side entry point | +| Model switching | Change code, credentials, and deployment configuration | Adjust channels, model mappings, groups, and routing | +| Availability | Each application implements its own retry and upstream-failure handling | Configure weights, priorities, retries, and failover centrally | +| Permissions and credentials | Credentials are scattered across applications and environment variables | Manage tokens, model scopes, quotas, and expiration centrally | +| Cost accounting | Provider bills are fragmented and difficult to attribute | Track usage by user, token, model, channel, and group | +| Troubleshooting | Logs are fragmented across providers | Observe requests, errors, retries, and latency at the gateway | -
-View common environment variables - -| Variable | Description | Default | -|--------|------|--------| -| `SESSION_SECRET` | Session secret; required for multi-node deployments | - | -| `CRYPTO_SECRET` | Encryption secret; required when using Redis or multi-node deployments | - | -| `SQL_DSN` | Database connection string | - | -| `REDIS_CONN_STRING` | Redis connection string | - | -| `STREAMING_TIMEOUT` | Streaming response timeout in seconds | `300` | -| `STREAM_SCANNER_MAX_BUFFER_MB` | Max per-line buffer for stream scanner; increase for large base64 image responses | `64` | -| `MAX_REQUEST_BODY_MB` | Maximum request body size after decompression; returns `413` when exceeded | `32` | -| `AZURE_DEFAULT_API_VERSION` | Default Azure API version | `2025-04-01-preview` | -| `ERROR_LOG_ENABLED` | Error log switch | `false` | -| `NODE_NAME` | Node name for multi-node log identification and asynchronous task settlement attribution | - | -| `PYROSCOPE_URL` | Pyroscope service URL | - | -| `PYROSCOPE_APP_NAME` | Pyroscope application name | `max-api` | -| `PYROSCOPE_BASIC_AUTH_USER` | Pyroscope Basic Auth username | - | -| `PYROSCOPE_BASIC_AUTH_PASSWORD` | Pyroscope Basic Auth password | - | -| `PYROSCOPE_MUTEX_RATE` | Pyroscope mutex sampling rate | `5` | -| `PYROSCOPE_BLOCK_RATE` | Pyroscope block sampling rate | `5` | -| `HOSTNAME` | Hostname label for Pyroscope | `max-api` | +In one sentence: **providers supply the models, Agent frameworks orchestrate the application, and MAX API provides unified access while enforcing governance boundaries.** -
+## 🚀 Quick start -### Docker Compose +The local experience uses SQLite by default and requires only Docker: ```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API +MAX_API_IMAGE=cscitechtop/max-api:latest@sha256:006d5d86887a261baab4d71ec3797d429e3771a4836e5899734aee0e7f66f2ab -# Modify docker-compose.yml: -# - Change default PostgreSQL / MySQL / Redis passwords -# - Set SESSION_SECRET, CRYPTO_SECRET, NODE_NAME as needed -# - Use a reverse proxy and HTTPS in production -docker compose up -d -``` - -### Docker Command +docker pull "$MAX_API_IMAGE" -**SQLite:** - -```bash -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest +docker run --name max-api -d --restart always -p 127.0.0.1:3000:3000 -e TZ=Asia/Shanghai -v ./data:/data "$MAX_API_IMAGE" ``` -**MySQL:** +Open , then: -```bash -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e SQL_DSN="root:123456@tcp(mysql:3306)/max-api" \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest -``` - -### Build Image from Source - -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API -docker build -t cscitechtop/max-api:latest . -``` - -> [!NOTE] -> `Dockerfile` downloads Go modules during the image build. For host builds or dependency/security updates, keep `go.mod` and `go.sum` committed together, run `go mod download && go mod verify`, then rebuild the binary or image; use `docker build --pull --no-cache -t cscitechtop/max-api:latest .` when base images need to be refreshed. +1. Create or confirm the administrator account. +2. Add an upstream channel and API key that you are legally authorized to use. +3. Create an access token and point your application's Base URL to MAX API. > [!TIP] -> The frontend uses Bun workspace. The build context must keep `web/package.json`, `web/bun.lock`, and `web/default/package.json`; otherwise `catalog:` dependencies cannot be resolved. - -### Multi-node Deployment Notes - +> Use stable releases in production. Preview releases are intended for testing and staged validation. Back up the database and prepare a rollback plan before upgrading. +> > [!WARNING] -> - All nodes must use the same `SESSION_SECRET`; otherwise login state will be inconsistent across nodes. -> - If shared Redis is used, all nodes must use the same `CRYPTO_SECRET`; otherwise encrypted data cannot be decrypted. -> - Set a stable `NODE_NAME` for each node to locate source nodes in logs, audit information, and asynchronous task settlement. -> - Production environments should use an external database, external Redis, HTTPS reverse proxy, and reliable backup strategy. - ---- +> SQLite is suitable for local evaluation, development, and small-scale tests. For production, use MySQL or PostgreSQL versions that remain within the vendor's security-support lifecycle (MySQL 8.4 LTS and PostgreSQL 14+ are recommended), together with Redis, HTTPS, backups, and recovery procedures. Compatibility minimums remain MySQL ≥ 5.7.8 and PostgreSQL ≥ 9.6, but those versions are not recommended for production. -## 🗺️ Roadmap +## ✨ Current capabilities -The following directions are planning items and may change based on maintenance cadence, real-world scenarios, and community needs. They are not time commitments. +The following capabilities are available in the current system: -- **Deeper model governance**: strengthen governance around model catalogs, pricing, permissions, mappings, capability tags, and provider changes. -- **Deeper AgentOps**: optimize call chains, cost attribution, failure diagnosis, and governance for Agents, tool calls, workflows, and MCP-style tools/services. -- **Multimodal task governance**: improve billing, rate limiting, status tracking, and result proxying for image, video, audio, and realtime interaction tasks. -- **Protocol conversion enhancement**: continue improving conversion among OpenAI Compatible, Responses, Claude Messages, Gemini, and other protocols. -- **Domestic model and platform tracking**: follow domestic model, cloud platform, pricing, and API protocol changes, and accumulate reusable channel, pricing, and task protocol configuration. -- **Provider adaptation templating**: make path overrides, task protocols, status mapping, error parsing, and result parsing easier to configure and reuse. -- **Governance audit and operations optimization**: improve request chains, cost tracking, error analysis, admin audit, log retention, and operations reports. -- **Organization-level operations**: enhance multi-tenant, group, billing, permission, risk control, and private deployment experience. +| Capability | Primary use | +|---|---| +| Unified model entry point | Connect OpenAI-Compatible APIs, Responses, Claude Messages, Gemini, Realtime, and multimodal task interfaces | +| Multi-provider routing | Manage channels, weights, priorities, groups, model mappings, retries, and cross-provider failover | +| Identity and access control | Manage users, tokens, model scopes, groups, quotas, expiration, rate limits, and administrator permissions | +| Cost and billing | Support multipliers, fixed pricing, expression billing, asynchronous task rate-cards, pre-charge, settlement, and failed-task refunds | +| Logs and audit | Inspect usage, errors, retries, and administrative operations by user, token, model, channel, group, and node | +| Intelligent Operations Center | Review active alerts, channel performance, model performance, system information, and billing-settlement reconciliation evidence | +| Private deployment | Support SQLite, MySQL, PostgreSQL, Redis, multiple nodes, and a separate log database | +| Upstream extensibility | Support protocol adapters, path overrides, parameter/Header overrides, model discovery, and task-status mappings | -Feature requests, issues, and improvement suggestions are welcome in [GitHub Issues](https://github.com/MAX-API-Next/MAX-API/issues). +### Use cases ---- +- **Internal model gateway for a team or organization**: manage users, tokens, models, providers, permissions, and costs centrally. +- **Runtime foundation for AI applications and Agents**: provide model access control, cost attribution, and failure diagnosis for applications, Agents, and workflows. +- **Multi-provider resilience and migration**: reduce dependence on a single upstream through model mapping, weighted routing, retries, and staged switching. +- **Multimodal task governance**: manage image, audio, video, embedding, reranking, and realtime conversation interfaces. +- **Private and compliant operations**: retain control of credentials, data, logs, audit, pricing, and deployment environments. -## ❓ FAQ +## 🩺 Intelligent Operations Center -
-Does MAX API provide model services or API keys? +**The Intelligent Operations Center is a major MAX API 2.0 update and a key step from a unified model gateway toward AGI-native governance and operations infrastructure.** -No. MAX API is a gateway governance layer for model and Agent workloads. It does not provide upstream model accounts, API keys, foundation model training, or model services. Users must obtain legally authorized upstream services themselves. +It consolidates production observation, resource alerts, model and channel performance, system information, and billing-settlement reconciliation in one administrator entry point. The current capability focuses on seeing problems, preserving evidence, notifying administrators, and enabling controlled review. It is not an autonomous Agent that automatically changes channels, routing, balances, or hosts. -
- -
-How does MAX API relate to Agent frameworks? +| Module | What it currently provides | +|---|---| +| Active alerts | Deduplicated alerts when CPU, memory, or disk on the current node remains above a threshold, plus recovery notifications; reuses existing administrator Email, Webhook, Bark, or Gotify configuration | +| Channel performance | Requests and errors, consumed quota, estimated success rate, log latency, retries, probe latency, and latest observation time; detail view shows the channel's model and group performance over the last 24 hours | +| Model performance | Aggregated channel count, requests and errors, consumed quota, estimated success rate, log latency, throughput, and retries; detail view includes group performance, latency trends, and availability trends | +| Billing-settlement reconciliation | Shows `pending` / `manual` positive final settlements, unsettled funds, retry state, and error evidence; root administrators can configure the default user-blocking policy, and administrators can atomically review batches by `id + revision` and close alerts | +| System information | Shows nodes, running instances, system tasks, and related information; this module continues to require super-administrator permission | -MAX API does not replace Dify, LangChain, MCP Server, workflow engines, or business Agent applications. It sits between those applications and upstream model services, handling model access, token isolation, cost accounting, routing resilience, log observability, and admin audit. - -
- -
-Why emphasize AI model governance? +The Active Alerts page reads current alert state every five seconds but does not trigger new detection or remediation. Channel and model lists query the latest hour by default and accept a custom `1–168` hour window. They do not continuously rescan large log databases: queries run only when the administrator selects “Apply filters” or “Refresh,” and detail data loads on demand. -In real organizations, a model is not just an API name. It also involves provider, pricing, context length, protocol format, permission scope, reliability, and audit boundaries. MAX API's value is to configure, observe, and account for these distributed variables uniformly. +Billing-settlement reconciliation strictly separates financial recovery state from operational alert state. “Review and close” records the administrator review and closes the current alert; it does not mark a settlement as `applied` and does not change balances, applied deltas, or effect state. Batch review is bound to the current financial revision. If a record changes after refresh, the old selection becomes invalid, preventing action based on stale evidence. -
+> [!NOTE] +> Current production-performance views primarily aggregate existing Consume/Error logs and `perf_metrics`. Estimated success rate is not a complete Relay Attempt success rate, while throughput and trends are performance-bucket approximations. When logging is disabled, historical data is missing, collection is disabled, a window has no samples, or a query fails, the UI displays the corresponding data-quality state. +> +> Active alerts depend on performance monitoring and resource-threshold configuration. A threshold of `0` disables that resource alert, and two consecutive valid samples are required before an alert fires. Alert state and the notification queue exist only in the current process memory: they do not survive a restart, and multiple nodes do not merge them into a cross-node Incident. Channel, model, and system observation remains read-only. Settlement review only updates review metadata and the user-blocking policy; it does not perform financial settlement. The Intelligent Operations Center does not automatically test, disable, reweight, switch channels, or repair hosts. -
-Which databases are supported? +The value of this stage is to complete the loop of seeing problems, notifying administrators, presenting evidence, and enabling controlled review—creating a foundation for unified Evidence, diagnostic Agents, Evaluators, and controlled automation. -SQLite, MySQL ≥ 5.7.8, and PostgreSQL ≥ 9.6 are supported. SQLite is suitable for local evaluation; MySQL or PostgreSQL with backups is recommended for production. +## 🔌 Models, interfaces, and extensibility -
+> Actual availability depends on your upstream authorization, channel configuration, model mapping, and provider support. MAX API governs these capabilities; it does not provide model services itself. -
-Can I migrate from New API / One API? +| Category | Interface or capability | +|---|---| +| General model interfaces | Chat Completions, Responses, Embeddings, Rerank, Images, Audio, and Video | +| Native and realtime protocols | Claude Messages, Google Gemini, OpenAI Realtime, and related entry points | +| Reasoning and tool calling | Reasoning Effort, function tools, Tool Call IDs, tool names, and multi-turn tool-response association, with protocol conversion based on upstream capability | +| Asynchronous tasks | Task submission, polling, status mapping, result proxying, and parameterized billing | +| Custom upstreams | Base URL, path, parameter, Header, status-field, and result-field mappings | -The project is compatible with the main data structures of New API and the original One API, so existing data can usually be reused. Back up your database and verify channels, multipliers, users, tokens, and logs in a test environment before migration. +Coverage includes OpenAI, Claude, Gemini, Azure, AWS Bedrock, Vertex AI, Ollama, and multiple domestic model platforms. MAX API can also govern Codex, Dify, RAGFlow, and multimodal task services. Exact support depends on the current release and channel type. -
- -
-What should I pay attention to in multi-node deployment? +### System flow and technology stack -Use the same `SESSION_SECRET` on all nodes. If shared Redis is used, also use the same `CRYPTO_SECRET`. Otherwise login state may be inconsistent, cached data may fail to decrypt, or task status may behave unexpectedly. +![MAX API system architecture](./docs/images/MAX-API架构图.png) -
+```text +Application / SDK / Agent + → Unified interface and identity authentication + → Model permissions, rate limits, budgets, and security checks + → Channel selection, mapping, and failure retry + → Upstream protocol adaptation + → Recoverable settlement, Evidence, logging, and audit + → Intelligent Operations Center and administrator governance +``` -
-What if image generation, streaming responses, or large responses are truncated? +The backend uses Go, Gin, and GORM. The frontend uses React 19, TypeScript, Base UI, and Tailwind CSS. The data layer supports SQLite, MySQL, and PostgreSQL, with optional Redis and a separate log database. Provider protocol adapters live in a dedicated Relay/Channel layer, billing and settlement remain inside a unified service boundary, and SmartOps presents read-only observation and constrained governance entry points. -Increase `STREAM_SCANNER_MAX_BUFFER_MB`. 4K images, base64 images, and long streaming responses may require a larger scan buffer. +## 🛡️ Governance and operations -
+For production, configure the system in this order: -
-What if a large request body returns 413? +1. Configure login, security limits, and user-registration policy. +2. Add legally authorized upstream channels and confirm model, capability, and protocol configuration. +3. Configure groups, tokens, model scopes, quotas, and prices by team, business, or environment. +4. Use a separate token for each application, Agent, or environment to avoid shared credentials and ambiguous cost attribution. +5. Configure retries, logs, and alerts, then continuously observe the system through dashboards and the Intelligent Operations Center. -Adjust `MAX_REQUEST_BODY_MB`. The limit is calculated based on the decompressed request body size to prevent very large requests or zip bombs from causing memory spikes. +For channel capability validation, expression billing, generic task protocols, administrator audit, and performance settings, see the [documentation](https://docs.max-api.ai). -
+## 🧭 Evolution roadmap -
-Can users see input/output content in admin log audit? +MAX API will continue to make **AI Models and Agents governance** its core. Starting from the unified gateway, intelligent operations, and recoverable settlement, it will gradually build Evidence, evaluation, policy, and controlled-execution capabilities for AGI applications. The long-term direction is not to let an unbounded Agent control production, but to create an engineering loop that is verifiable, approvable, stoppable, and reversible. -Normal user log APIs filter admin-only fields, so normal users cannot see admin audit content in self-service usage logs. Database administrators, system administrators, or users with admin log API permissions may still access related data, so permissions must be strictly controlled according to compliance requirements. +| Stage | Status | Focus | +|---|---|---| +| Unified gateway and intelligent operations | **Available now** | Access, authentication, routing, billing, logging, resource alerts, channel/model performance, system information, and billing-settlement reconciliation | +| Evidence fact layer | **Near-term development** | Unify model requests, system logs, metrics, Tasks, routing, policies, settlement, and audit events behind sanitized, permission-limited, read-only Agent interfaces | +| Open evaluation and governance templates | **Planned** | Build model/protocol compatibility tests, anonymized incident samples, evaluation sets, Runbooks, Detectors, and industry governance templates with the community | +| Controlled autonomous operations | **Long-term blueprint** | Evaluate low-risk automated actions under Policy, Budget, Approval, Shadow, Canary, and Rollback constraints | +| Controlled capability evolution | **Long-term blueprint** | Generate, test, and review candidate improvements inside isolated Coding Workspaces without directly modifying production | +| AGI engineering loop | **Long-term direction** | Connect Evidence, evaluation, governance policies, human approval, and reversible execution into a verifiable loop | -
+MAX API is not a foundation model and does not claim to have already achieved AGI or autonomous operations. Long-term capabilities will be validated gradually only after Evidence, permission, budget, approval, and rollback boundaries are in place. -
-Why does Docker build report unresolved `catalog:` dependencies? +## 🚢 Preview deployment -The frontend uses Bun workspace, and `catalog:` dependencies are defined in `web/package.json`. Do not overwrite the workspace root `package.json` with `web/default/package.json` during build, and keep `web/bun.lock`. +The following steps are for Preview testing and staged validation. For production, use a stable release and keep the same verification and rollback process. -
+Docker Compose is recommended: ---- +```bash +MAX_API_VERSION=v2.0.0-smartops.pre1 +MAX_API_COMMIT=b7096156549edc930ca244891afb1ba5632dbe8f +git clone --branch "$MAX_API_VERSION" --depth 1 https://github.com/MAX-API-Next/MAX-API.git +cd MAX-API -## 🔗 Related Projects +actual_commit="$(git rev-parse HEAD)" +if [ "$actual_commit" != "$MAX_API_COMMIT" ]; then + echo "Unexpected commit: $actual_commit" >&2 + exit 1 +fi -| Project | Description | -|------|------| -| [One API](https://github.com/songquanpeng/one-api) | MIT License | -| [New API](https://github.com/QuantumNous/new-api) | AGPLv3 License | -| [Midjourney-Proxy](https://github.com/novicezk/midjourney-proxy) | Apache-2.0 License | -| [Suno API](https://github.com/Suno-API/Suno-API) | MIT License | +# Update database and Redis passwords and configure secrets in docker-compose.yml +docker compose up -d +``` -### Companion Tools +### Deployment checklist -| Project | Description | -|------|------| -| [max-api-key-tool](https://github.com/MAX-API-Next/MAX-API-key-tool) | Key quota lookup tool | -| [max-api-horizon](https://github.com/MAX-API-Next/MAX-API-horizon) | High-performance optimized MAX API edition | +| Component | Recommendation | +|---|---| +| Database | Use a MySQL or PostgreSQL release still covered by vendor security support (MySQL 8.4 LTS and PostgreSQL 14+ recommended), with backup and recovery configured | +| Cache | In-memory cache is suitable for one node; Redis is recommended for multiple nodes | +| Entry point | Configure an HTTPS reverse proxy, request-size limits, and trusted-network policy | +| Secrets | Set a random `SESSION_SECRET` explicitly; `CRYPTO_SECRET` is an optional override that falls back to `SESSION_SECRET` when unset, and must be shared across Redis/multi-node deployments when set | +| Nodes | Give every node a stable and unique `NODE_NAME` | +| Logging | Configure `LOG_SQL_DSN`, cleanup, and retention based on compliance and operational requirements | ---- +Multi-node deployments must share `SESSION_SECRET` while using a different `NODE_NAME` for each node. `CRYPTO_SECRET` is an optional override that falls back to `SESSION_SECRET` when unset; if explicitly set, use the same value on every node. Use `LOG_SQL_DSN` for a separate log database and enable `ERROR_LOG_ENABLED` when error-performance statistics are needed. See the [documentation](https://docs.max-api.ai) for complete environment variables and source-build instructions. -## 📚 Documentation and Support - -| Resource | Link | -|------|------| -| Official documentation | [MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) | -| Issue tracker | [GitHub Issues](https://github.com/MAX-API-Next/MAX-API/issues) | -| Latest releases | [Releases](https://github.com/MAX-API-Next/MAX-API/releases) | -| DeepWiki | [Ask DeepWiki](https://deepwiki.com/MAX-API-Next/MAX-API) | - -### Derivative Use and Community Acknowledgement - -If you build a derivative version of this project for your own use, you are welcome to keep the project source or a community acknowledgement clearly visible on the homepage, in the footer, or on the About page by choosing either option below: - -- Link to the project: [MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) -- Acknowledge the community: [MAX-API-Next](https://github.com/MAX-API-Next) - -Reference frontend embed code (React / Tailwind CSS; keep either item as needed): - -```tsx -

- Built from{' '} - - MAX-API-Next/MAX-API - {' '} - · Thanks to the{' '} - - MAX-API-Next community - -

-``` +## 🤝 Project origins, acknowledgements, and derivative use -By meeting either attribution requirement above and keeping the link clearly visible, you automatically receive a temporary commercial license for this project, with no separate application or approval required. This is not a perpetual license and remains valid only while the display requirement continues to be met. Its validity period and any later changes are governed by the latest notice published in this README or by the official community. +MAX API continues development from the open-source work of [One API](https://github.com/songquanpeng/one-api) and [New API](https://github.com/QuantumNous/new-api). We thank the upstream projects, their contributors, and everyone who contributes protocol adapters, tests, documentation, translations, and issue reports. -This project is developed from [One API](https://github.com/songquanpeng/one-api) and [New API](https://github.com/QuantumNous/new-api). At this stage, MAX API builds on those foundations by strengthening its AI API gateway and governance capabilities, expanding features, and fixing bugs. Commercial use must also comply with the One API MIT License and the New API AGPLv3 License, subject to each upstream project's current `LICENSE` file. The temporary commercial license provided by this project does not replace or waive any upstream open-source license obligations. +Under [NOTICE](./NOTICE) and AGPLv3 Section 7, a modified version that presents a user interface must keep all of the following in a prominent, visible About, legal, footer, or attribution location: -If the display requirement is no longer met, or the temporary license expires, is amended, or is terminated by notice, you must comply with AGPLv3 or obtain separate written authorization. For a long-term commercial license, contact: maxapi@max-api.ai. +- A link to the original MAX API project: [MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) +- The exact MAX API NOTICE attribution: `Frontend design and development by MAX API contributors.` +- A link to the upstream New API project: [QuantumNous/new-api](https://github.com/QuantumNous/new-api) +- The exact New API NOTICE attribution: `Frontend design and development by New API contributors.` +- A prominent statement that the version was modified, including a relevant modification date -Issues, documentation improvements, provider adaptation experience, deployment practices, and code contributions are welcome. +An acknowledgement of the [MAX-API-Next community](https://github.com/MAX-API-Next) is welcome as an optional addition, but it does not replace the required project links, exact attributions, or change marking. ---- +Continuing to meet these display and NOTICE requirements automatically grants a non-perpetual temporary commercial license without a separate application or approval. This additional permission covers only material that the MAX API project maintainers have the right to license and does not waive AGPLv3 or the licensing obligations of One API, New API, or other upstream projects. The latest conditions are governed by the formal README and official community notices. ## 📜 License This project is licensed under the [GNU Affero General Public License v3.0 (AGPLv3)](./LICENSE). -In addition to the default AGPLv3 license, self-use derivative projects that meet the “Derivative Use and Community Acknowledgement” conditions above automatically receive the non-perpetual temporary commercial license described there. This temporary license covers only additions and modifications that the MAX API project maintainers have the right to license; it does not include or replace licensing from upstream projects such as One API and New API. - -If you modify this project and provide it to users over a network, please understand and comply with AGPLv3 source availability obligations. For commercial cooperation, institutional cooperation, or other licensing questions, contact: maxapi@max-api.ai. - ---- - -## 🌟 Star History +The temporary commercial license covers only additions and modifications that the MAX API project maintainers have the right to license. It does not include, replace, or waive the licensing obligations of One API, New API, or other upstream projects. Commercial use must also comply with the One API MIT License, the New API AGPLv3 License, and the latest license terms of each upstream project. -
- -[![Star History Chart](https://api.star-history.com/svg?repos=MAX-API-Next/MAX-API&type=Date)](https://star-history.com/#MAX-API-Next/MAX-API&Date) - -
+If you modify this project and provide it to users over a network, please understand and comply with AGPLv3 source-availability obligations. For a long-term commercial license, institutional cooperation, or other licensing questions, contact maxapi@max-api.ai. --- @@ -767,9 +354,9 @@ If you modify this project and provide it to users over a network, please unders ### 💖 Thank you for using MAX API -If this project helps you, please consider giving us a ⭐ Star. +If this project helps you, please consider giving it a ⭐ Star, following Releases, reporting a reproducible Issue, or joining the MAX-API-Next community. -**[Official Documentation](https://github.com/MAX-API-Next/MAX-API)** • **[Issues](https://github.com/MAX-API-Next/MAX-API/issues)** • **[Releases](https://github.com/MAX-API-Next/MAX-API/releases)** +**[Project repository](https://github.com/MAX-API-Next/MAX-API)** • **[Contribute](https://github.com/MAX-API-Next/MAX-API/issues)** • **[Latest releases](https://github.com/MAX-API-Next/MAX-API/releases)** • **[MAX-API-Next community](https://github.com/MAX-API-Next)** Built with ❤️ by MAX-API-Next diff --git a/README.fr.md b/README.fr.md index 55a4bd42..8dc19fff 100644 --- a/README.fr.md +++ b/README.fr.md @@ -1,10 +1,14 @@ -
+# MAX API -![max-api](/web/default/public/logo.png) +
-# MAX API +![MAX API](./web/default/public/logo.png) + +**AI Models and Agents governance, exploitation intelligente et collaboration ouverte pour l'ère des applications AGI** + +**MAX API 2.0 : entrer dans l'ère de l'exploitation intelligente · évoluer d'une passerelle de modèles unifiée vers une infrastructure native de gouvernance et d'exploitation AGI** -🍥 **Gouvernance des modèles IA, AgentOps et infrastructure de services pour applications AGI** +[Consulter les notes de version MAX API 2.0 Preview](https://github.com/MAX-API-Next/MAX-API/releases/tag/v2.0.0-smartops.pre1)

简体中文 | @@ -15,668 +19,334 @@

- licensereleasedockerGoReportCard + + licence + + version + + docker + + GoReportCard + +

+ +

+ ⭐ Ajouter une Star • + 💬 Rejoindre la communauté • + 📚 Documentation • + 🚀 Versions

- Positionnement • - Canaux de publication • - Gouvernance • - Cas d'usage • + Communauté • Démarrage • - Capacités • - Configuration • - Architecture • - Modèles & API • - Déploiement • - FAQ • - Licence + Pourquoi MAX API • + Orientation AGI • + Capacités • + SmartOps • + Déploiement Preview

--- -## 📝 Description du projet - -MAX API est un projet d'infrastructure pour la gouvernance des modèles IA, l'AgentOps et les services applicatifs. Il est initié, maintenu et exploité sur le long terme par des passionnés d'AGI issus d'organismes de recherche et d'universités. Il fournit aux développeurs, chercheurs, équipes et organisations une couche de service stable et réutilisable. Le projet se concentre sur les problèmes d'exploitation qui apparaissent lorsque les applications IA passent en production : multiplication des modèles, évolution fréquente des API amont, chaînes d'appels Agent plus longues, pression accrue sur les coûts et l'audit. MAX API fournit une couche unifiée d'accès, d'authentification, de routage, de facturation, d'observabilité et de gouvernance entre applications, Agents, utilisateurs, organisations et fournisseurs de modèles. - -En pratique, MAX API n'est pas seulement un proxy de requêtes. C'est une passerelle exploitable pour applications AI-ready et charges Agent, qui regroupe normalisation des protocoles, différences fournisseurs, pics de trafic, longs flux streaming, gros corps de requête, cache multi-nœud, audit des coûts et observabilité des performances dans une même frontière de gouvernance. - -Axes d'investissement continus : - -- **Gouvernance des modèles IA** : suivi continu des mises à jour de modèles, des changements d'API, des différences de paramètres, des règles de prix et des protocoles de tâches chez OpenAI, Azure OpenAI, AWS Bedrock, Vertex AI, Ollama, ainsi que chez DeepSeek, Qwen / Alibaba Cloud Model Studio, Zhipu GLM, Kimi, Doubao / Volcano Engine, Tencent Hunyuan, Baidu ERNIE / Qianfan, iFlytek Spark, MiniMax, 01.AI, SiliconFlow et d'autres plateformes. Le projet suit aussi Dify, RAGFlow, Kling, Seedance et d'autres écosystèmes applicatifs ou multimodaux. -- **Gouvernance AI Agent / AgentOps** : amélioration de la gouvernance des jetons, du contrôle d'accès aux modèles, du traçage des appels, de l'attribution des coûts, du diagnostic d'erreurs et de l'audit des journaux pour les Agents, workflows et appels d'outils. -- **Gouvernance de configuration des canaux** : matrice de capacités et validation de configuration lors de la création ou modification des canaux, avec affichage de `chat/completions`, `responses`, `embeddings`, `rerank`, `video tasks`, découverte de modèles, et alertes sur Base URL, JSON, région Vertex AI, identifiants Codex ou placeholders de tâches vidéo. -- **Optimisation opérationnelle et gouvernance des coûts** : routage, retry, limitation, préfacturation, remboursement en cas d'échec, observabilité, statistiques de coûts et analyse d'exploitation. Les scénarios token peuvent utiliser la facturation par expression et les scénarios de tâches asynchrones peuvent utiliser des rate-cards paramétrées. - -> [!IMPORTANT] -> - Lors de la fourniture de services publics d'IA générative, les utilisateurs doivent respecter les obligations réglementaires applicables et gérer eux-mêmes les déclarations, licences, sécurité de contenu, vérification d'identité, conservation des journaux, fiscalité, paiement et autorisations amont requises dans leur juridiction. -> - Les capacités sensibles comme l'audit des journaux et la conservation de contenu ne doivent être activées qu'avec une base légale, une information claire, une isolation des permissions et des mesures de sécurité des données. -> - MAX API fournit une couche de gouvernance de passerelle pour les charges de travail de modèles et d'Agents. Il ne fournit pas de comptes amont, de clés API, d'entraînement de modèles de base, et ne remplace pas Dify, LangChain, MCP Server ni les frameworks d'orchestration d'Agents. - ---- - -## 🚦 Canaux de publication +MAX API se place entre les applications, les Agents et les services de modèles en amont. Il sert de passerelle de modèles unifiée, de plan de contrôle de gouvernance et de point d'entrée pour l'exploitation. La communauté MAX-API-Next développe le projet autour de l'ingénierie AGI concrète et accueille les développeurs, chercheurs, équipes d'ingénierie en entreprise, passionnés de technologie dans les universités et contributeurs open source. Notre objectif est de construire les fondations dont les applications AGI ont réellement besoin : accès aux modèles, permissions, maîtrise des coûts, Evidence, exploitation intelligente et contrôles de sécurité. -Les versions actuelles de MAX API sont divisées entre versions stables et versions Preview. Les versions Preview exposent plus tôt les nouvelles capacités et corrections afin que la communauté et les opérateurs puissent valider la compatibilité, la stabilité et la sécurité en environnement réel. Une version stable est publiée après 1 semaine de fonctionnement stable de la Preview correspondante, afin de réduire les risques de mise à niveau en production et d'améliorer la sécurité et la fiabilité du système. +Dans le domaine de l'AGI, nous voulons **livrer en continu des technologies avancées et vérifiables, transformer les problèmes réels de production en capacités d'ingénierie ouvertes et bâtir une communauté de recherche et de contribution.** -Pour la production, privilégiez les versions stables. Utilisez les versions Preview dans des environnements de test ou de canary lorsque vous devez valider à l'avance de nouvelles fonctionnalités, corrections ou évolutions de compatibilité, avec sauvegarde de base de données et plan de rollback avant mise à niveau. +## 🌐 Rejoindre la communauté MAX-API-Next ---- - -## 🎯 Positionnement du projet - -À l'ère des applications AGI, MAX API se concentre sur une infrastructure ouverte de gouvernance des modèles IA et des AI Agents, afin de construire une couche de service, de gouvernance et d'exploitation permettant aux développeurs et organisations d'exécuter durablement applications IA et charges Agent : - -- **Plan de gouvernance des modèles** : gestion unifiée des entrées de modèles, canaux, fournisseurs, protocoles, mappings, règles tarifaires, protocoles de tâches et interfaces multimodales. -- **Plan de contrôle AgentOps** : ne remplace pas les frameworks d'orchestration Agent ; fournit au niveau passerelle la gouvernance des jetons, le contrôle d'accès aux modèles, les journaux d'appel, le suivi des coûts, le diagnostic d'anomalies et l'analyse opérationnelle. -- **Plan de configuration des canaux** : réduit les risques de mauvaise configuration grâce aux matrices de capacités, validations de formulaires, découverte de modèles et modèles de protocole. -- **Couche d'adaptation protocoles/fournisseurs** : suit les API officielles internationales, les plateformes de modèles chinoises et les API OpenAI-compatible / non standard, puis les normalise en interfaces applicatives stables. -- **Gouvernance coût, quota et fiabilité** : routage de canaux, distribution pondérée, retry, limitation, préfacturation, remboursement d'échec, facturation par expression, prix fixes, rate-cards de tâches, multiplicateurs et statistiques d'usage. -- **Gouvernance performance et scalabilité** : cache Redis / mémoire, limitation des requêtes modèles, timeouts streaming, tampons pour grandes réponses, limites de corps de requête, cache disque, profiling Pyroscope et arrêt gracieux pour les déploiements mono ou multi-nœuds. -- **Couche d'exploitation et d'audit organisationnelle** : utilisateurs, groupes, déploiement privé, rétention des données, audit et optimisation continue. -- **Modèles de gouvernance réutilisables** : capitalisation des templates de canaux, protocoles de tâches, configurations de prix, pratiques de déploiement et retours d'exploitation. - ---- - -## 🧠 Cadre de gouvernance - -MAX API place l'exécution des modèles IA et des AI Agents dans un cadre configurable, observable, calculable et auditable. - -| Objet gouverné | Capacités MAX API | Objectif | -|----------|-------------------|------| -| Actifs modèles | Listes de modèles, mappings, groupes, restrictions, règles de prix et gestion multimodale | Savoir quels modèles existent, qui peut les utiliser, comment ils sont facturés et comment les basculer | -| Canaux amont | Fournisseurs, poids, groupes, état, clés, Base URL, overrides de chemins, matrice de capacités, validation, découverte et retry | Réduire les risques d'indisponibilité, hausse de prix, limites, erreurs de configuration ou changements d'API | -| Formats de protocole | OpenAI Compatible, Responses, Claude Messages, Gemini, Realtime, protocole vidéo générique et conversions | Donner aux applications des interfaces stables plutôt que les exposer aux différences de fournisseurs | -| Jetons Agent | API Key, groupes de jetons, périmètre de modèles, quotas, expiration et contrôle d'accès | Fournir aux Agents et workflows des identifiants indépendants, révocables et limitables | -| Usage et coûts | Journaux, statistiques, facturation par expression, JSON par paliers, rate-card de tâches, préfacturation et remboursements | Attribuer les coûts par utilisateur, groupe, jeton, modèle, canal et nœud | -| Tâches asynchrones | Soumission, polling, mapping d'état, proxy de résultat et facturation de tâches vidéo | Gouverner les tâches multimodales longues, multi-états et multi-fournisseurs | -| Audit et sécurité | Audit admin, journaux d'erreurs, limites de requêtes, timeout streaming, login et permissions | Fournir une frontière d'audit contrôlée en déploiement privé et contexte conforme | -| Exploitation organisationnelle | Utilisateurs, groupes, solde, paiement, paramètres système, tableaux de bord et configuration ops | Soutenir l'exploitation continue d'équipes, institutions, entreprises ou communautés | - ---- - -## 🧩 Cas d'usage - -- **Plateforme interne de gouvernance des modèles IA** : gestion centralisée des utilisateurs, jetons, modèles, canaux, groupes, permissions, prix et factures. -- **Socle d'exécution et de gouvernance Agent** : passerelle de modèles, isolation des jetons, contrôle des coûts, observabilité, diagnostic et audit pour Agents, workflows et outils. -- **Centre d'adaptation modèles chinois et multi-fournisseurs** : suivi des API et prix, réduction du coût d'adaptation via configuration de canaux, mappings, overrides de chemins et templates de protocole. -- **Plateforme de gouvernance multimodale** : accès unifié au texte, image, vidéo, audio, embeddings, rerank et temps réel, avec gestion d'état, proxy de résultat et facturation pour les tâches asynchrones. -- **Comptabilité des coûts modèles et Agents** : quotas, calcul de coûts, statistiques de facturation et analyse par utilisateur, jeton, modèle, canal et groupe. -- **Environnement privé et conforme** : pour les équipes ou organisations qui doivent maîtriser clés, données, permissions, journaux, audit et stratégie tarifaire. - ---- - -## 🚀 Démarrage rapide +MAX API est plus qu'un dépôt de code. C'est une collaboration ouverte de long terme autour des AI Models, Agents, AgentOps et de l'ingénierie AGI. Que vous exploitiez une passerelle de modèles, développiez des Agents, adaptiez de nouveaux modèles, travailliez sur l'évaluation et la gouvernance, ou amélioriez la documentation et les traductions, vous êtes les bienvenus. -SQLite est utilisé par défaut ; aucun service de base de données externe n'est requis pour un essai local. +**Rejoignez la communauté pour suivre les versions, les évolutions de modèles et de protocoles, les pratiques de déploiement, les pistes de diagnostic et les possibilités de contribution.** -> [!WARNING] -> SQLite est réservé à l'évaluation locale, au développement et aux tests à petite échelle. Son utilisation est déconseillée en production : les requêtes concurrentes, les déploiements multi-instances, les volumes importants de journaux ou de données d'usage, les migrations, les opérations de sauvegarde/restauration et les transactions longues peuvent provoquer des contentions de verrouillage, des écritures bloquées, des migrations lentes ou en échec, ainsi que des problèmes de disponibilité ou de maintenance des données. En production, utilisez MySQL ≥ 5.7.8 ou PostgreSQL ≥ 9.6 avec un plan fiable de sauvegarde et de restauration. - -```bash -# 1. Récupérer l'image -docker pull cscitechtop/max-api:latest - -# 2. Lancer le service et persister les données dans ./data -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest - -# 3. Ouvrir la console -# Navigateur : http://localhost:3000 -``` - -Pour la production, utilisez Docker Compose et configurez explicitement base de données, Redis, secret de session, secret de chiffrement et répertoire de journaux. - -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API - -# Modifier docker-compose.yml selon les mots de passe et variables nécessaires -docker compose up -d -``` - -> [!WARNING] -> Si vous exploitez ce projet comme service public d'IA générative ou service API, finalisez d'abord les autorisations amont, obligations réglementaires, sécurité de contenu, vérification d'identité, conservation des journaux, fiscalité, paiement et conditions utilisateur. - ---- - -## ✨ Capacités clés - -### Gouvernance des modèles IA - -| Capacité | Description | -|------|------| -| Entrée modèle unifiée | Prend en charge OpenAI-compatible, Responses, Claude Messages, Gemini, Realtime et d'autres protocoles via une passerelle unique | -| Pool multi-fournisseurs | OpenAI, Azure, Claude, Gemini, AWS Bedrock, Vertex AI, Ollama, et suivi/adaptation de DeepSeek, Qwen, Zhipu GLM, Kimi, Doubao, Hunyuan, ERNIE, iFlytek Spark, MiniMax, 01.AI, SiliconFlow, etc. | -| Adaptation de l'écosystème amont | Gouvernance des interfaces Codex, Dify, RAGFlow, Kling, Seedance et autres plateformes applicatives, Agent ou multimodales | -| Mapping et périmètre d'accès | Listes de modèles par canal, mappings, groupes utilisateur, groupes de jetons et restrictions de modèles | -| Matrice de capacités des canaux | Affiche `chat/completions`, `responses`, `Claude Messages`, `Gemini native`, `embeddings`, `images`, `audio`, `rerank`, `video tasks`, `model discovery` | -| Validation des canaux | Vérifie API Key, modèles, Base URL, configuration JSON, région Vertex AI, identifiants Codex, découverte de modèles et placeholders vidéo | -| Gouvernance multimodale | Chat, image, vidéo, audio, embeddings, rerank, temps réel, et gestion des tâches asynchrones vidéo | -| Protocole vidéo générique | Configure soumission, requête, progression, mapping d'état, erreur et chemins de résultats ; le passthrough et les réécritures du corps utilisent les paramètres de canal existants ; chemins par défaut `/v1/videos/create` et `/v1/videos/{task_id}` | -| Conversion protocolaire et amonts personnalisés | Conversions OpenAI Compatible, Responses, Chat Completions, Claude Messages, Gemini, ainsi que URL amont autorisées, overrides et règles de parsing de tâches | - -### Gouvernance AI Agent / AgentOps - -| Capacité | Description | -|------|------| -| Isolation des jetons Agent | Créer des API Key indépendantes pour Agents, workflows, plugins, appels d'outils ou utilisateurs | -| Contrôle d'accès modèle | Contrôler modèles, canaux et quota par utilisateur, jeton, groupe, restriction de modèle et politique de canal | -| Observabilité de chaîne d'appels | Journaux, statistiques, canal touché, latence, erreurs et retries pour diagnostiquer les Agents | -| Attribution des coûts | Statistiques par modèle, canal, utilisateur, groupe, jeton et nœud | -| Audit administrateur | Audit côté admin en déploiement privé ; les API de journaux utilisateur filtrent les champs réservés aux administrateurs | -| Tableau de bord ops | Analyses, gestion utilisateurs, gestion canaux, paramètres système et analyse d'exploitation | - -### Gouvernance des coûts, de la facturation et de la fiabilité - -**Expressions de prix des modèles** - -- **Une expression = une règle complète de tarification token** : paliers, cache hit, tokens image/audio, remises horaires et majorations dynamiques peuvent être décrits en une ligne. -- **Le prix correspond au prix réel** : les coefficients peuvent représenter directement des dollars par million de tokens ; `p * 2.5` signifie 2,5 USD par million de tokens d'entrée. Le mode multiplicateur historique reste compatible. -- **Édition visuelle + brute** : saisie guidée ou édition directe de l'expression, avec modèles prédéfinis. -- **Maintenance JSON unifiée** : `Tiered billing JSON` maintient plusieurs `{ enabled, expr }` et met à jour `billing_mode` et `billing_expr` de manière atomique. -- **Normalisation automatique des tokens** : sépare cache, image, audio et autres sous-catégories pour éviter la double facturation. - -**Facturation des tâches et fiabilité** - -- Rate-card paramétrée pour tâches asynchrones vidéo, avec prix selon modèle, `vendor`, durée, qualité, audio, entrée vidéo, etc. `task_billing_setting.rate_cards` peut séparer Sora, Veo, Seedance, Kling et autres fournisseurs. -- Compatible avec facturation à l'usage, par appel, cache hit, multiplicateurs de modèle, groupe et canal. -- Préfacturation, remboursement d'échec, traitement d'exceptions et journaux de consommation. -- Routage pondéré, retry, contournement des canaux désactivés et routage par modèle. -- Cache Redis et mémoire pour déploiement mono ou multi-nœud. - -### Gouvernance performance et scalabilité - -| Capacité | Description | -|------|------| -| Cache et extension multi-nœud | Déploiement mono-nœud avec cache mémoire, multi-nœud avec Redis ; les caches utilisateur, jeton, affinité de canal et quota réduisent les lectures répétées en base, tandis que `SESSION_SECRET`, `CRYPTO_SECRET` et `NODE_NAME` gardent sessions, chiffrement et attribution des journaux cohérents | -| Limitation et protection de capacité | Limites globales API / Web, limites d'endpoints critiques, recherche, requêtes modèles et quotas par groupe ; compteurs via Redis ou mémoire | -| Streaming et grandes requêtes | `STREAMING_TIMEOUT`, `STREAM_SCANNER_MAX_BUFFER_MB`, `MAX_REQUEST_BODY_MB`, `MAX_FILE_DOWNLOAD_MB` contrôlent longs flux, grandes lignes SSE, corps décompressés et téléchargements distants | -| Réglage des connexions relais | `RELAY_TIMEOUT`, `RELAY_IDLE_CONN_TIMEOUT`, `RELAY_MAX_IDLE_CONNS` et `RELAY_MAX_IDLE_CONNS_PER_HOST` configurent timeouts et pool HTTP amont | -| Cache disque et observabilité | Les paramètres de performance peuvent activer le cache disque pour grands corps, définir seuil et capacité ; les endpoints ops peuvent inspecter / nettoyer ce cache, et Pyroscope collecte CPU, mémoire, goroutines, mutex et block profiles | -| Arrêt gracieux et persistance | `SHUTDOWN_TIMEOUT_SECONDS` et `QUOTA_DATA_CACHE_SAVE_TIMEOUT_SECONDS` aident à fermer HTTP et sauvegarder le cache quota avant sortie quand c'est possible | - -### Sécurité et gestion d'organisation - -- JWT, WebAuthn/Passkeys, OAuth, OIDC, Telegram, Discord, LinuxDO et autres méthodes de connexion. -- Contrôle des administrateurs, utilisateurs, groupes, jetons et accès modèles. -- Limites de taille de requête, timeout streaming, journaux d'erreurs et health checks. -- Secret de session, secret de chiffrement et cache Redis partagé en multi-nœud. - ---- - -## 🆚 Pourquoi utiliser une passerelle - -| Dimension | SDK / API officiels en direct | Via la passerelle MAX API | -|------|------------------------|-------------------| -| Accès modèles | Un SDK, une auth et des paramètres par fournisseur | Entrée unique, intégration unique, réutilisation multi-modèles | -| Gouvernance modèles | Modèles, prix, permissions et canaux dispersés | Gestion unifiée des modèles, canaux, mappings, groupes, quotas et prix | -| Accès Agent | Les Agents détiennent directement les clés amont | Jetons indépendants avec limites de modèles, quota, expiration et groupe | -| Différences de protocole | L'application adapte Claude, Gemini, Responses, etc. | La passerelle convertit les protocoles et adapte les fournisseurs | -| Échecs | Retry, fallback et normalisation d'erreurs côté application | Retry de canaux, routage pondéré et traitement d'erreurs intégrés | -| Performance et extension | L'application gère timeouts, limites, pools de connexions et cache | La passerelle centralise timeouts streaming, limites de requêtes, cache Redis / mémoire, réglage de pool et observabilité | -| Coûts | Factures dispersées, attribution difficile | Quotas, facturation, statistiques et journaux unifiés par jeton et modèle | -| Audit | Journaux applicatifs dispersés | Entrée d'audit admin unifiée, filtrage des champs admin pour utilisateurs | -| Privé | Clés, journaux et stratégie tarifaire dispersés | Auto-hébergement et contrôle des clés, données, journaux et politiques | - ---- - -## 🧭 Vue d'ensemble de l'architecture - -MAX API utilise une architecture en couches : les requêtes des applications, SDK ou Agents entrent par une interface unifiée, passent par routeur, middleware, contrôleurs et services métier, puis sont adaptées par la couche relay vers le fournisseur amont. La couche données et cache assure persistance et accélération pour gouvernance de modèles, jetons Agent, facturation, journaux, audit et état des tâches. - -```mermaid -flowchart LR - Client[Client / SDK / Agent] --> Router[Router
Routage] - Router --> MW[Middleware
Auth · Limite · Dispatch · Logs] - MW --> Ctrl[Controller
Handlers] - Ctrl --> Svc[Service
Gouvernance modèles · AgentOps · Audit facturation] - Svc --> Relay[Relay
Proxy / Conversion] - Relay --> Adapters[Adaptateurs de canaux
OpenAI · Claude · Gemini · Plateformes chinoises · Amonts personnalisés] - Adapters --> Upstream[(Services de modèles amont)] - Svc --> Model[Model
GORM] - Model --> DB[(SQLite · MySQL · PostgreSQL)] - Svc --> Cache[(Redis · Cache mémoire)] -``` - -### Structure des répertoires - -| Répertoire | Rôle | -|------|------| -| `router/` | Routage HTTP : API, relay, dashboard et web | -| `controller/` | Handlers, parsing des paramètres, entrées métier authentifiées et réponses | -| `service/` | Logique métier : modèles, AgentOps, journaux, facturation, audit, tâches, canaux et configuration | -| `model/` | Modèles de données et accès DB via GORM, compatible SQLite, MySQL, PostgreSQL | -| `relay/` | Relay API IA, conversion de protocoles et adaptation fournisseur | -| `relay/channel/` | Adaptateurs openai, claude, gemini, aws, etc. | -| `middleware/` | Auth, limitation, CORS, logs, distribution de requêtes et contexte | -| `setting/` | Prix modèles, facturation tâches, opérations, système, sécurité et performance | -| `common/` | Utilitaires JSON, chiffrement, Redis, limitation et variables d'environnement | -| `dto/` / `types/` | Types de requêtes, réponses, erreurs et formats relay | -| `constant/` | Types d'API, types de canaux et clés de contexte | -| `i18n/` / `oauth/` / `pkg/` | i18n backend, OAuth et packages internes | -| `web/` | Conteneur du frontend ; thème par défaut dans `web/default/` | - -### Stack technique - -| Couche | Technologie | -|------|------| -| Backend | Go 1.25+, Gin, GORM v2 | -| Frontend | React 19, TypeScript, Rsbuild, Base UI, Tailwind CSS | -| Gestion de paquets | Bun workspace | -| Base de données | SQLite / MySQL ≥ 5.7.8 / PostgreSQL ≥ 9.6 | -| Cache | Redis + cache mémoire | -| Authentification | JWT, WebAuthn/Passkeys, OAuth, OIDC | - ---- - -## 🤖 Prise en charge des modèles et interfaces IA +

+ Groupe QQ : 950126533 • + Groupe WeChat : recherchez MAX-API +

-> Les modèles réellement disponibles dépendent de vos autorisations amont, de la configuration des canaux, des mappings et du support fournisseur. MAX API gouverne ces capacités, mais ne fournit pas les services de modèles amont. +| Point d'entrée | Utilité | +|---|---| +| [MAX-API-Next sur GitHub](https://github.com/MAX-API-Next) | Suivre les projets communautaires, les orientations techniques et la collaboration ouverte | +| [Issues MAX API](https://github.com/MAX-API-Next/MAX-API/issues) | Signaler un problème reproductible, proposer une amélioration ou partager un changement de compatibilité | +| [Versions MAX API](https://github.com/MAX-API-Next/MAX-API/releases) | Suivre les versions stables et Preview | +| [Ask DeepWiki](https://deepwiki.com/MAX-API-Next/MAX-API) | Rechercher et comprendre rapidement le code | +| Coopération technique et écosystème | Contacter `maxapi@max-api.ai` | -| Type | Description | -|------|------| -| OpenAI-Compatible | Chat Completions, Embeddings, Images, Audio et interfaces compatibles | -| OpenAI Responses | Requêtes Responses, relay et conversion compatible Responses ↔ Chat Completions | -| Claude Messages | Conversion Claude Messages ↔ format OpenAI-compatible | -| Google Gemini | Chat, texte et conversion compatible `/v1/responses` | -| Azure OpenAI | Azure OpenAI et Realtime | -| AWS Bedrock | Accès Bedrock Runtime | -| Plateformes et applications amont | AWS, Azure, Vertex, Ollama, Codex, Dify, RAGFlow, Kling, Seedance, etc. | -| Modèles et plateformes chinoises | DeepSeek, Qwen / Alibaba Cloud Model Studio, Zhipu GLM, Kimi, Doubao / Volcano Engine, Tencent Hunyuan, Baidu ERNIE / Qianfan, iFlytek Spark, MiniMax, 01.AI, SiliconFlow, etc. | -| `rerank` | Modèles Cohere, Jina et autres pour RAG et chaînes de recherche Agent | -| Midjourney / Suno / Dify | Adaptateurs image, musique et workflow | -| API de tâches vidéo | `/v1/videos/create`, `/v1/videos/{task_id}` : soumission, passthrough du corps ou overrides de paramètres, polling, mapping d'état, proxy de résultat et facturation paramétrée | -| Amonts personnalisés | URL autorisées, règles d'adaptation, conversion Responses / Chat, overrides, mapping d'état, chemin d'erreur et parsing de résultat | +### Profils de contributeurs recherchés -### Interfaces principales +- **Contributeurs modèles et protocoles** : adaptation de nouveaux modèles et fournisseurs, Reasoning, appels d'outils et protocoles de tâches multimodales. +- **Développeurs d'Agents et d'applications** : pratiques d'intégration et de gouvernance pour Dify, RAGFlow, Codex, MCP, workflows et Agents de recherche. +- **Ingénieurs fiabilité et sécurité** : tests multi-bases, reprise des tâches asynchrones, sécurité des règlements, cohérence du cache et frontières de permissions. +- **Contributeurs documentation et communauté** : guides de déploiement, FAQ, exemples, traductions, expériences reproductibles et accueil des nouveaux contributeurs. +- **Chercheurs et développeurs d'évaluations** : Evidence, Evaluators, Detectors, Runbooks et architectures d'autonomie contrôlée.
-Voir les catégories - -- Chat : `/v1/chat/completions` -- Responses : `/v1/responses` -- Images : `/v1/images/*` -- Audio : `/v1/audio/*` -- Vidéo : `/v1/videos/*` -- Embeddings : `/v1/embeddings` -- Rerank : `/v1/rerank` -- Realtime : interface compatible OpenAI Realtime -- Claude Messages : entrée native Claude -- Gemini : entrée format Google Gemini +Voir les axes de collaboration, les principes et les façons de participer -
+| Axe | Contributions possibles | +|---|---| +| Écosystème modèles et fournisseurs | Adaptateurs modèles/protocoles, tests de compatibilité, changements de listes et de dépréciation, modèles de canaux | +| AgentOps et gouvernance des applications AGI | Exemples d'intégration Agent, frontières de jetons et de permissions, gouvernance des coûts, pratiques d'exploitation | +| SmartOps et Evidence | Incidents anonymisés, définitions de métriques, règles d'alerte, qualité des données, méthodes de diagnostic et d'évaluation | +| Fiabilité, facturation et sécurité | Règlement idempotent, reprise asynchrone, régressions multi-bases, cohérence du cache, vérification des opérations à risque | +| Documentation, tutoriels et localisation | Déploiement, architecture, FAQ, cas d'usage, traductions et guides de contribution | -### Prise en charge de Reasoning Effort +Fournissez si possible une reproduction minimale, la version, l'environnement, des journaux anonymisés ou des preuves de test. Les changements de protocole, de base de données ou de contrat utilisateur doivent décrire la compatibilité, la migration et le rollback. Ne soumettez pas de véritables clés API, données clients, enregistrements bruts de paiement, journaux privés ou données non autorisées. Les contributions touchant aux fonds, à la sécurité, aux secrets, aux données de production ou à l'exécution automatisée exigent des tests plus stricts, une revue indépendante et un responsable clairement identifié. -
-Voir des exemples de noms de modèles +Vous pouvez commencer par : -- `o3-mini-high`, `o3-mini-medium`, `o3-mini-low` -- `gpt-5-high`, `gpt-5-medium`, `gpt-5-low` -- `claude-3-7-sonnet-20250219-thinking` -- `gemini-2.5-flash-thinking`, `gemini-2.5-flash-nothinking`, `gemini-2.5-pro-thinking`, `gemini-2.5-pro-thinking-128` -- Les suffixes `-low`, `-medium`, `-high` peuvent aussi contrôler l'effort de raisonnement Gemini. +1. Signaler un problème reproductible, une différence de protocole ou un changement de compatibilité d'un modèle. +2. Ajouter à une issue un test en échec, un cas multi-base, une régression frontend ou une Evidence anonymisée. +3. Améliorer la configuration des modèles/canaux, le déploiement, les FAQ, l'architecture ou les traductions. +4. Partager des pratiques anonymisées d'intégration Agent, de gouvernance des coûts, de SmartOps ou de déploiement privé. +5. Proposer un Evaluator, Detector, Runbook ou une architecture d'autonomie contrôlée avec des frontières de capacité et de risque explicites.
---- - -## 🔧 Configuration de gouvernance +Documentation associée : [MAX-API-Docs](https://github.com/MAX-API-Next/MAX-API-Docs) (guides de déploiement, de configuration et d'utilisation). -### Configuration initiale recommandée +Les fournisseurs de modèles, projets Agent/workflow, communautés open source, chercheurs et équipes d'ingénierie sont invités à collaborer. Les partenariats formels, annonces conjointes ou usages du nom d'une institution nécessitent l'autorisation explicite des deux parties. -1. Après le déploiement, ouvrez la console et créez ou confirmez le compte administrateur. -2. Configurez paramètres système, inscription, méthodes de connexion et limites de sécurité. -3. Ajoutez les canaux amont avec API Key autorisée, Base URL, modèles, mappings et paramètres. -4. Configurez groupes utilisateurs, groupes de jetons, restrictions de modèles, quotas et règles de prix. -5. Créez des jetons indépendants pour applications, Agents ou workflows avec périmètre et quota. -6. Configurez retry, journaux, cache et statistiques de consommation. -7. Pour l'audit de contenu côté admin, activez « System Settings → Security & Limits → Log Audit » en contexte conforme, et vérifiez que « Record quota usage (Log Maintenance) » est activé. - -### Matrice de capacités et validation des canaux - -À la création ou modification d'un canal, le système affiche une matrice de capacités et des résultats de validation. Les noms techniques restent en anglais (`chat/completions`, `responses`, `embeddings`, `rerank`, `video tasks`) et les descriptions expliquent les usages. - -La validation couvre notamment : API Key manquante, liste de modèles vide, Base URL ou configuration requise absente, Base URL terminée par `/v1`, JSON non objet, région Vertex AI sans `default`, clé de service invalide, identifiants Codex incomplets, découverte de modèles non supportée, ou chemin de requête vidéo sans `{task_id}`, `{operation_name}` ou `{upstream_task_id}`. - -### Protocole générique de tâches vidéo - -Les fournisseurs vidéo diffèrent souvent par chemins, task ID, état, progression, erreurs et URL de résultat. MAX API généralise cette capacité aux canaux OpenAI, Ali, Gemini, MiniMax, Vertex AI, VolcEngine, Kling, Jimeng, Vidu, Doubao Video, Sora, etc. - -- **Override de chemins uniquement** : configurer `submit_path` et `query_path` tout en conservant le parseur officiel du canal. -- **Parsing complet** : définir `task_protocol = "generic_video_task"` et configurer task ID, état, progression, URL de résultat, erreur et mapping d'état. -- **Traitement du corps** : le protocole vidéo générique ne définit plus de mode de génération du corps séparé. Utilisez `Pass Through Body` au niveau du canal pour transmettre le JSON client tel quel, et `Param Override` pour les réécritures, valeurs par défaut ou coordinations de headers. - -Chemins par défaut : - -```json -{ - "task_protocol": "generic_video_task", - "task_protocol_config": { - "submit_path": "/v1/videos/create", - "query_path": "/v1/videos/{task_id}", - "task_id_path": "task_id", - "status_path": "status", - "progress_path": "progress", - "result_url_paths": ["result.primary_url", "result.urls.0", "data.result.primary_url", "url", "video_url", "download_url"], - "error_message_path": "error_message", - "status_map": { "queued": "QUEUED", "running": "IN_PROGRESS", "succeeded": "SUCCESS", "failed": "FAILURE" } - } -} -``` +> [!IMPORTANT] +> Lors de la fourniture au public de services d'IA générative, les opérateurs sont responsables des autorisations amont, déclarations ou licences, de la sécurité des contenus, de la vérification d'identité, de la conservation des journaux, de la fiscalité, des paiements, des conditions utilisateur et de toute obligation applicable dans leur juridiction. L'audit des journaux et la conservation de contenu ne doivent être activés qu'avec une base légale, une information claire, une isolation des permissions et des mesures adaptées de sécurité des données. -Les chemins de requête prennent en charge `{task_id}`, `{operation_name}` et `{upstream_task_id}`. `{operation_name}` peut conserver des chemins multi-segments pour Gemini / Vertex. Le contenu vidéo peut être proxyfié via `/v1/videos/{task_id}/content` afin de masquer le domaine amont, avec authentification, protection SSRF et ports autorisés. +Console d'administration MAX API -### Maintenance JSON de la facturation +## 🧠 Orientation technique pour l'AGI -- **Tiered billing JSON** : maintient plusieurs règles `{ enabled, expr }` et synchronise `billing_mode` / `billing_expr`. -- **Task rate-card JSON** : maintient `task_billing_setting.rate_cards` pour les tâches asynchrones, avec partition `vendor` pour Sora, Veo, Seedance, Kling, etc. +Les applications AGI ne dépendront pas éternellement d'un seul modèle, d'un seul protocole ou de requêtes ponctuelles. Elles nécessitent raisonnement multi-modèles, appels d'outils, tâches multimodales, exécutions longues, contraintes de coûts, Evidence de production et gestion récupérable des échecs. MAX API part de ces problèmes d'ingénierie vérifiables pour construire une fondation d'AI Models and Agents governance. -Les modèles vidéo comme Seedance 2.0 peuvent utiliser la résolution, l'entrée vidéo et d'autres paramètres de requête dans les multiplicateurs ou les rate-cards. Avec le passthrough ou les overrides de paramètres, gardez les champs finaux envoyés en amont alignés avec les champs de facturation. +| Orientation technique | Fondations actuelles | Valeur pour les applications AGI | +|---|---|---| +| Accès multi-modèles et multi-protocoles | OpenAI Compatible, Responses, Claude Messages, Gemini, Realtime, protocoles multimodaux et tâches asynchrones | Offre aux applications et Agents un point d'entrée relativement stable malgré l'évolution de l'écosystème | +| Compatibilité du raisonnement et du contexte d'outils | Reasoning Effort, définitions d'outils, Tool Calls, association des réponses d'outils et conversion de contexte multi-tour | Réduit la perte d'informations de raisonnement et de sémantique des outils lors d'un changement de fournisseur | +| Plan de contrôle de gouvernance | Utilisateurs, jetons, périmètres de modèles, groupes, routage, limites, quotas, prix et permissions administrateur | Crée des frontières distinctes d'identité, d'accès et de budget pour chaque Agent, environnement et tâche | +| Facturation récupérable et cycle de vie des tâches | Préfacturation, règlement final, enregistrements idempotents, remboursement des échecs, polling asynchrone et états de rapprochement manuel | Évite doublons de débit, remboursements erronés et résultats intraçables pendant les longues tâches, retries et fenêtres d'échec | +| Evidence et exploitation intelligente | Journaux, erreurs, retries, buckets de performance, alertes actives, performance canal/modèle et preuves de règlement | Fonde diagnostic, évaluation et futures recommandations d'Agents sur des faits traçables plutôt que sur les seuls prompts | +| Sécurité et gouvernance organisationnelle | Passkeys, 2FA, revérification par périmètre, révocation de session, audit et limitation des opérations sensibles | Maintient une responsabilité explicite autour des configurations, secrets et opérations à risque | +| Autonomie contrôlée et évolution d'ingénierie | **Vision long terme** : Policy, Budget, Approval, Shadow, Canary, Rollback et Coding Workspaces isolés | Exige que l'automatisation soit évaluée, contrainte et auditée avant toute action de production à faible risque | -```json -{ - "model-name": { - "enabled": true, - "expr": "len <= 200000 ? tier(\"standard\", p * 3 + c * 15) : tier(\"long_context\", p * 6 + c * 22.5)" - } -} -``` +### Principes techniques -```json -{ - "vendor/model-name": { - "vendor": "kling", - "unit": "second", - "quantity_field": "duration", - "default_quantity": 5, - "strict": true, - "defaults": { "quality": "std", "has_audio": "false" }, - "rows": [{ "id": "std_no_audio", "match": { "quality": "std", "has_audio": "false" }, "unit_price": 0.6 }] - } -} -``` +- **Evidence before Action** : établir des faits vérifiables avant tout diagnostic, recommandation ou action automatisée. +- **Governance before Autonomy** : identité, permissions, budgets, approbation, audit et rollback doivent précéder l'autonomie. +- **One Billing Truth** : facturation, quota et règlement de production conservent une source de vérité unique ; Agents et plugins ne créent pas une seconde comptabilité. +- **Compatibility by Design** : continuer à prendre en charge SQLite, MySQL, PostgreSQL, plusieurs protocoles fournisseurs et des contrats applicatifs portables. +- **Open Collaboration, Safe Boundaries** : ouvrir les adaptateurs, tests, documents, évaluations et conceptions de gouvernance, tout en maintenant les opérations de production, financières, de secrets et de publication sous approbation explicite. -### Entrées d'exploitation courantes +### Points forts techniques de MAX API 2.0 -| Fonction | Description | -|------|------| -| Gestion des canaux | Fournisseurs, mappings, poids, clés, chemins, état, matrice et validation | -| Modèles et prix | Modèles, prix, expressions, JSON par paliers, rate-cards et affichage | -| Gestion des jetons | Jetons pour applications, Agents, workflows, outils ou utilisateurs | -| Gestion utilisateurs | Utilisateurs, groupes, soldes, permissions et états | -| Journaux d'usage | Appels, consommation, latence, erreurs, canaux et audit visible admin | -| Paramètres système | Sécurité, audit, prix, tâches, opérations, logs, paiement et site | -| Tableau de bord | Requêtes, usage modèles, consommation, état canaux et coûts des jetons Agent | - ---- +- **Evidence-driven SmartOps** : regroupe alertes de ressources, performance canal/modèle, états de qualité des données et preuves de règlement dans un même point d'entrée, tout en conservant la frontière entre revue humaine et état financier réel. +- **Évolution continue pour les protocoles de modèles avancés** : améliore Reasoning, clés de cache, paramètres de pénalité, définitions d'outils et Tool Context multi-tour pour Responses, Claude Messages, Gemini et Ollama. +- **Sémantique récupérable de facturation et de tâches asynchrones** : règlement idempotent, effets persistants, identifiants de tâche et états pending/manual explicites empêchent les retries de créer doublons, remboursements incorrects ou pertes de tâche. +- **Revérification par périmètre pour les opérations à risque** : Passkeys, 2FA, Telegram, API Tokens et révocation de session utilisent une scope-bound step-up verification ; `session_generation` invalide rapidement les anciennes sessions. +- **Compatibilité multi-base et validation continue** : les chemins de données essentiels prennent en charge SQLite, MySQL et PostgreSQL ; tests Go, tests frontend Bun, vérification TypeScript, règle du wrapper JSON et synchronisation du miroir de tests constituent les barrières de publication. -## 🚢 Déploiement +## 💡 Pourquoi MAX API -### Exigences +| Dimension | Connexion directe à plusieurs fournisseurs | Avec MAX API | +|---|---|---| +| Intégration applicative | Maintenir des SDK, protocoles, authentifications et formats d'erreur distincts | Utiliser un point d'entrée applicatif relativement stable | +| Changement de modèle | Modifier le code, les secrets et la configuration de déploiement | Ajuster les canaux, mappings, groupes et règles de routage | +| Disponibilité | Chaque application gère ses retries et pannes amont | Centraliser poids, priorités, retries et bascules | +| Permissions et secrets | Secrets dispersés dans les applications et variables d'environnement | Gérer jetons, périmètres de modèles, quotas et expirations au même endroit | +| Comptabilité des coûts | Factures fournisseurs dispersées et difficiles à attribuer | Suivre l'usage par utilisateur, jeton, modèle, canal et groupe | +| Diagnostic | Journaux fragmentés entre fournisseurs | Observer requêtes, erreurs, retries et latence au niveau de la passerelle | -| Composant | Exigence | -|------|------| -| Moteur conteneur | Docker / Docker Compose | -| Base locale | SQLite, uniquement pour l'évaluation locale, le développement ou les tests à petite échelle ; monter `/data` avec Docker | -| Base de production | MySQL ≥ 5.7.8 ou PostgreSQL ≥ 9.6 avec un plan fiable de sauvegarde et de restauration | -| Cache | Mémoire en mono-nœud, Redis recommandé en multi-nœud | -| Build frontend | Bun workspace, conserver `web/package.json` et `web/bun.lock` | -| Build source | Utiliser la version de Go déclarée dans `go.mod` (actuellement Go 1.25.1+) avec `go.sum` ; après une mise à jour de dépendances ou de sécurité, exécuter `go mod download`, `go mod verify`, puis reconstruire | +En une phrase : **les fournisseurs livrent les modèles, les frameworks Agent orchestrent l'application et MAX API unifie l'accès tout en faisant respecter les frontières de gouvernance.** -### Variables d'environnement recommandées - -
-Voir les variables courantes - -| Variable | Description | Défaut | -|--------|------|--------| -| `SESSION_SECRET` | Secret de session, requis en multi-nœud | - | -| `CRYPTO_SECRET` | Secret de chiffrement, requis avec Redis ou multi-nœud | - | -| `SQL_DSN` | Chaîne de connexion DB | - | -| `REDIS_CONN_STRING` | Chaîne Redis | - | -| `STREAMING_TIMEOUT` | Timeout streaming en secondes | `300` | -| `STREAM_SCANNER_MAX_BUFFER_MB` | Buffer max par ligne pour streaming | `64` | -| `MAX_REQUEST_BODY_MB` | Taille max du body décompressé | `32` | -| `AZURE_DEFAULT_API_VERSION` | Version API Azure par défaut | `2025-04-01-preview` | -| `ERROR_LOG_ENABLED` | Activation des journaux d'erreurs | `false` | -| `NODE_NAME` | Nom du nœud pour logs multi-nœuds et attribution des règlements de tâches asynchrones | - | -| `PYROSCOPE_URL` | URL Pyroscope | - | -| `PYROSCOPE_APP_NAME` | Nom d'application Pyroscope | `max-api` | -| `PYROSCOPE_BASIC_AUTH_USER` | Utilisateur Basic Auth | - | -| `PYROSCOPE_BASIC_AUTH_PASSWORD` | Mot de passe Basic Auth | - | -| `PYROSCOPE_MUTEX_RATE` | Taux mutex | `5` | -| `PYROSCOPE_BLOCK_RATE` | Taux block | `5` | -| `HOSTNAME` | Label hôte | `max-api` | - -
+## 🚀 Démarrage rapide -### Docker Compose +L'expérience locale utilise SQLite par défaut et ne nécessite que Docker : ```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API -# Modifier mots de passe, secrets et proxy HTTPS selon besoin -docker compose up -d -``` +MAX_API_IMAGE=cscitechtop/max-api:latest@sha256:006d5d86887a261baab4d71ec3797d429e3771a4836e5899734aee0e7f66f2ab -### Docker +docker pull "$MAX_API_IMAGE" -```bash -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest +docker run --name max-api -d --restart always -p 127.0.0.1:3000:3000 -e TZ=Asia/Shanghai -v ./data:/data "$MAX_API_IMAGE" ``` -```bash -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e SQL_DSN="root:123456@tcp(mysql:3306)/max-api" \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest -``` +Ouvrez ensuite , puis : -### Construire depuis les sources - -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API -docker build -t cscitechtop/max-api:latest . -``` - -> [!NOTE] -> `Dockerfile` télécharge les modules Go pendant la construction de l'image. Pour une construction locale ou après une mise à jour de dépendances / sécurité, conservez `go.mod` et `go.sum` ensemble, exécutez `go mod download && go mod verify`, puis reconstruisez le binaire ou l'image ; utilisez `docker build --pull --no-cache -t cscitechtop/max-api:latest .` lorsque les images de base doivent être rafraîchies. +1. Créez ou confirmez le compte administrateur. +2. Ajoutez un canal amont et une clé API que vous êtes légalement autorisé à utiliser. +3. Créez un jeton d'accès et pointez la Base URL de votre application vers MAX API. > [!TIP] -> Le frontend utilise Bun workspace. Conservez `web/package.json`, `web/bun.lock` et `web/default/package.json`, sinon les dépendances `catalog:` ne seront pas résolues. - -### Notes multi-nœuds - +> Utilisez les versions stables en production. Les versions Preview sont destinées aux tests et à la validation progressive. Sauvegardez la base et préparez un rollback avant toute mise à niveau. +> > [!WARNING] -> - Tous les nœuds doivent partager `SESSION_SECRET`. -> - Avec Redis partagé, tous les nœuds doivent partager `CRYPTO_SECRET`. -> - Définissez un `NODE_NAME` stable pour identifier les nœuds dans les logs, l'audit et les règlements de tâches asynchrones. -> - En production, utilisez DB externe, Redis externe, HTTPS et sauvegardes fiables. +> SQLite convient à l'évaluation locale, au développement et aux tests de petite taille. En production, utilisez des versions de MySQL ou PostgreSQL toujours couvertes par le support de sécurité du fournisseur (MySQL 8.4 LTS et PostgreSQL 14+ recommandés), avec Redis, HTTPS, sauvegardes et procédures de reprise. Les minimums de compatibilité restent MySQL ≥ 5.7.8 et PostgreSQL ≥ 9.6, mais ces versions ne sont pas recommandées en production. ---- +## ✨ Capacités actuelles -## 🗺️ Feuille de route +Les capacités suivantes sont disponibles dans le système actuel : -- **Approfondissement de la gouvernance des modèles** : catalogue, prix, permissions, mappings, tags de capacités et changements fournisseurs. -- **Approfondissement AgentOps** : chaînes d'appels, attribution des coûts, diagnostic, outils et services MCP-style. -- **Gouvernance multimodale** : facturation, limitation, suivi d'état et proxy de résultats pour image, vidéo, audio et temps réel. -- **Conversions de protocoles** : OpenAI Compatible, Responses, Claude Messages, Gemini et autres. -- **Suivi des modèles et plateformes chinoises** : API, prix, protocoles, canaux, prix et tâches réutilisables. -- **Templates fournisseurs** : overrides, protocoles, mapping d'état, parsing d'erreurs et résultats. -- **Audit et opérations** : chaînes de requêtes, coûts, erreurs, audit admin, rétention et rapports. -- **Opérations organisationnelles** : multi-tenant, groupes, facturation, permissions, contrôle des risques et déploiement privé. +| Capacité | Usage principal | +|---|---| +| Point d'entrée modèles unifié | Connecter OpenAI Compatible, Responses, Claude Messages, Gemini, Realtime et les interfaces de tâches multimodales | +| Routage multi-fournisseurs | Gérer canaux, poids, priorités, groupes, mappings, retries et bascule entre fournisseurs | +| Identité et contrôle d'accès | Gérer utilisateurs, jetons, périmètres de modèles, groupes, quotas, expiration, limitations et permissions administrateur | +| Coûts et facturation | Multiplicateurs, prix fixes, facturation par expression, rate-cards de tâches asynchrones, préfacturation, règlement et remboursement d'échec | +| Journaux et audit | Consulter usage, erreurs, retries et opérations d'administration par utilisateur, jeton, modèle, canal, groupe et nœud | +| Centre d'exploitation intelligente | Examiner alertes actives, performance des canaux et modèles, informations système et Evidence de rapprochement des règlements | +| Déploiement privé | SQLite, MySQL, PostgreSQL, Redis, plusieurs nœuds et base de journaux séparée | +| Extensibilité amont | Adaptateurs de protocole, overrides de chemin, paramètre/Header, découverte de modèles et mappings d'état de tâche | -Les demandes et suggestions sont bienvenues dans [GitHub Issues](https://github.com/MAX-API-Next/MAX-API/issues). +### Cas d'usage ---- +- **Passerelle interne pour une équipe ou organisation** : gérer utilisateurs, jetons, modèles, fournisseurs, permissions et coûts au même endroit. +- **Fondation d'exécution pour applications IA et Agents** : contrôle d'accès aux modèles, attribution des coûts et diagnostic pour applications, Agents et workflows. +- **Résilience et migration multi-fournisseurs** : réduire la dépendance à un seul amont grâce aux mappings, routage pondéré, retries et bascule progressive. +- **Gouvernance des tâches multimodales** : gérer images, audio, vidéo, embeddings, reranking et conversation temps réel. +- **Exploitation privée et conforme** : conserver la maîtrise des secrets, données, journaux, audits, prix et environnements de déploiement. -## ❓ FAQ +## 🩺 Centre d'exploitation intelligente -
MAX API fournit-il des services de modèles ou des clés API ? +**Le Centre d'exploitation intelligente est une évolution majeure de MAX API 2.0 et une étape clé entre la passerelle de modèles unifiée et une infrastructure native de gouvernance et d'exploitation AGI.** -Non. MAX API est une couche de gouvernance de passerelle. Il ne fournit pas de comptes, clés, entraînement ou services de modèles amont. +Il regroupe l'observation de production, les alertes de ressources, la performance des modèles et canaux, les informations système et le rapprochement des règlements de facturation dans une entrée administrateur unique. La capacité actuelle vise à voir les problèmes, préserver les preuves, notifier les administrateurs et permettre une revue contrôlée. Ce n'est pas un Agent autonome qui modifie automatiquement canaux, routage, soldes ou hôtes. -
- -
Quel est le lien avec les frameworks Agent ? - -MAX API ne remplace pas Dify, LangChain, MCP Server, moteurs de workflow ou applications Agent. Il se place entre eux et les modèles amont pour gérer accès, jetons, coûts, routage, logs et audit. - -
- -
Pourquoi parler de gouvernance de modèles IA ? - -Dans une organisation, un modèle implique fournisseur, prix, contexte, protocole, permissions, fiabilité et audit. MAX API unifie configuration, observation et calcul. - -
+| Module | Contenu actuellement fourni | +|---|---| +| Alertes actives | Alertes dédupliquées lorsque CPU, mémoire ou disque du nœud courant reste au-dessus d'un seuil, avec notification de rétablissement ; réutilise la configuration Email, Webhook, Bark ou Gotify de l'administrateur | +| Performance des canaux | Requêtes et erreurs, quota consommé, taux de succès estimé, latence des journaux, retries, latence de probe et dernière observation ; le détail montre les performances modèles/groupes des dernières 24 heures | +| Performance des modèles | Nombre de canaux, requêtes et erreurs, quota consommé, taux de succès estimé, latence des journaux, débit et retries ; le détail fournit performances par groupe, tendances de latence et de disponibilité | +| Rapprochement des règlements | Affiche les règlements finaux positifs `pending` / `manual`, fonds non réglés, retries et preuves d'erreur ; les root administrators configurent la politique de blocage utilisateur par défaut et les administrateurs examinent atomiquement des lots par `id + revision` puis ferment les alertes | +| Informations système | Affiche les nœuds, instances actives, tâches système et informations associées ; ce module exige toujours le rôle super-administrateur | -
Quelles bases de données sont supportées ? +La page des alertes actives lit l'état toutes les cinq secondes, mais ne déclenche ni nouvelle détection ni réparation. Les listes de canaux et modèles interrogent la dernière heure par défaut et acceptent une fenêtre personnalisée de `1–168` heures. Elles ne rescannent pas continuellement de grandes bases de journaux : la requête s'exécute uniquement avec « Appliquer les filtres » ou « Actualiser », et les détails sont chargés à la demande. -SQLite, MySQL ≥ 5.7.8 et PostgreSQL ≥ 9.6. SQLite convient aux essais ; MySQL ou PostgreSQL est recommandé en production. +Le rapprochement des règlements sépare strictement l'état de reprise financière de l'état d'alerte opérationnelle. « Examiner et fermer » enregistre la revue et ferme l'alerte courante ; l'action ne marque pas le règlement comme `applied` et ne change ni le solde, ni l'écart appliqué, ni l'état de l'effet. La revue en lot est liée à la révision financière courante. Si un enregistrement change après actualisation, l'ancienne sélection devient invalide afin d'empêcher une action fondée sur une preuve obsolète. -
- -
Peut-on migrer depuis New API / One API ? - -Les principales structures sont compatibles. Sauvegardez la base et vérifiez canaux, multiplicateurs, utilisateurs, jetons et journaux en environnement de test. +> [!NOTE] +> Les vues de performance de production agrègent principalement les journaux Consume/Error et `perf_metrics`. Le taux de succès estimé n'est pas un taux complet de Relay Attempt ; débit et tendances sont des approximations par bucket. Lorsque les journaux sont désactivés, l'historique absent, la collecte arrêtée, la fenêtre vide ou la requête en échec, l'interface affiche l'état de qualité des données correspondant. +> +> Les alertes actives dépendent du suivi de performance et des seuils de ressources. Un seuil à `0` désactive l'alerte correspondante et deux échantillons valides consécutifs sont requis avant déclenchement. L'état et la file de notifications ne résident que dans la mémoire du processus courant : ils ne survivent pas au redémarrage et plusieurs nœuds ne les fusionnent pas en Incident multi-nœud. L'observation des canaux, modèles et du système reste en lecture seule. La revue de règlement ne met à jour que les métadonnées de revue et la politique de blocage utilisateur ; elle n'exécute aucun règlement financier. Le Centre d'exploitation intelligente ne teste, désactive, repondère, bascule ou répare jamais automatiquement. -
+Cette étape ferme d'abord la boucle « voir le problème, notifier l'administrateur, présenter les preuves, permettre une revue contrôlée », puis prépare une base pour Evidence unifiée, Agents de diagnostic, Evaluators et automatisation contrôlée. -
Points d'attention en multi-nœud ? +## 🔌 Modèles, interfaces et extensibilité -Utilisez le même `SESSION_SECRET` partout ; avec Redis partagé, utilisez aussi le même `CRYPTO_SECRET`. +> La disponibilité réelle dépend de vos autorisations amont, de la configuration des canaux, des mappings de modèles et du support fournisseur. MAX API gouverne ces capacités ; il ne fournit pas lui-même de service de modèles. -
+| Catégorie | Interface ou capacité | +|---|---| +| Interfaces générales | Chat Completions, Responses, Embeddings, Rerank, Images, Audio et Video | +| Protocoles natifs et temps réel | Claude Messages, Google Gemini, OpenAI Realtime et entrées associées | +| Raisonnement et appels d'outils | Reasoning Effort, outils fonctionnels, Tool Call IDs, noms d'outils et association multi-tour des réponses, avec conversion selon les capacités amont | +| Tâches asynchrones | Soumission, polling, mapping d'état, proxy de résultat et facturation paramétrée | +| Amonts personnalisés | Mappings de Base URL, chemin, paramètres, Header, champ d'état et champ de résultat | -
Réponses image, streaming ou grosses réponses tronquées ? +La couverture inclut OpenAI, Claude, Gemini, Azure, AWS Bedrock, Vertex AI, Ollama et plusieurs plateformes de modèles chinoises. MAX API peut également gouverner Codex, Dify, RAGFlow et des services de tâches multimodales. Le périmètre exact dépend de la version et du type de canal. -Augmentez `STREAM_SCANNER_MAX_BUFFER_MB`. +### Flux système et stack technique -
+![Architecture système MAX API](./docs/images/MAX-API架构图.png) -
Requête trop grande avec 413 ? +```text +Application / SDK / Agent + → Interface unifiée et authentification + → Permissions modèles, limites, budgets et contrôles de sécurité + → Sélection du canal, mapping et retry d'échec + → Adaptation du protocole amont + → Règlement récupérable, Evidence, journaux et audit + → Centre d'exploitation intelligente et gouvernance administrateur +``` -Ajustez `MAX_REQUEST_BODY_MB`, calculé après décompression. +Le backend utilise Go, Gin et GORM. Le frontend utilise React 19, TypeScript, Base UI et Tailwind CSS. La couche de données prend en charge SQLite, MySQL et PostgreSQL, avec Redis et une base de journaux séparée en option. Les adaptateurs fournisseurs vivent dans une couche Relay/Channel dédiée, la facturation et le règlement restent dans une frontière de service unifiée, et SmartOps expose des observations en lecture seule avec des entrées de gouvernance limitées. -
+## 🛡️ Gouvernance et exploitation -
Les utilisateurs voient-ils les contenus d'audit admin ? +Pour la production, configurez le système dans cet ordre : -Les API de journaux utilisateur filtrent les champs réservés admin. Les administrateurs système ou DB peuvent toujours accéder aux données, donc les permissions doivent être strictement contrôlées. +1. Configurer la connexion, les limites de sécurité et la politique d'inscription. +2. Ajouter des canaux amont légalement autorisés et vérifier modèles, capacités et protocoles. +3. Configurer groupes, jetons, périmètres de modèles, quotas et prix par équipe, activité ou environnement. +4. Utiliser un jeton distinct par application, Agent ou environnement afin d'éviter le partage de secrets et l'ambiguïté d'attribution des coûts. +5. Configurer retries, journaux et alertes, puis observer le système avec les tableaux de bord et le Centre d'exploitation intelligente. -
+Pour la validation des capacités de canaux, la facturation par expression, les protocoles génériques de tâches, l'audit administrateur et les réglages de performance, consultez la [documentation](https://docs.max-api.ai). -
Pourquoi Docker signale des dépendances `catalog:` non résolues ? +## 🧭 Feuille de route -Le frontend utilise Bun workspace ; `catalog:` est défini dans `web/package.json`. Ne remplacez pas ce fichier par `web/default/package.json` et conservez `web/bun.lock`. +MAX API continuera de placer **AI Models and Agents governance** au cœur du projet. À partir de la passerelle unifiée, de l'exploitation intelligente et du règlement récupérable, il développera progressivement les capacités Evidence, évaluation, Policy et exécution contrôlée pour les applications AGI. L'objectif n'est pas de laisser un Agent sans frontières contrôler la production, mais de construire une boucle d'ingénierie vérifiable, approuvable, arrêtable et réversible. -
+| Étape | État | Priorité | +|---|---|---| +| Passerelle unifiée et exploitation intelligente | **Disponible** | Accès, authentification, routage, facturation, journaux, alertes de ressources, performance canal/modèle, informations système et rapprochement des règlements | +| Couche factuelle Evidence | **Développement proche** | Unifier requêtes de modèles, journaux système, métriques, Tasks, routage, Policies, règlements et événements d'audit derrière des interfaces Agent anonymisées, limitées et en lecture seule | +| Évaluations ouvertes et modèles de gouvernance | **Planifié** | Construire avec la communauté des tests de compatibilité, incidents anonymisés, jeux d'évaluation, Runbooks, Detectors et modèles de gouvernance métier | +| Exploitation autonome contrôlée | **Vision long terme** | Évaluer des actions automatisées à faible risque sous contraintes Policy, Budget, Approval, Shadow, Canary et Rollback | +| Évolution contrôlée des capacités | **Vision long terme** | Générer, tester et revoir des améliorations candidates dans des Coding Workspaces isolés sans modifier directement la production | +| Boucle d'ingénierie AGI | **Orientation long terme** | Relier Evidence, évaluation, politiques de gouvernance, approbation humaine et exécution réversible dans une boucle vérifiable | ---- +MAX API n'est pas un modèle de fondation et ne prétend pas avoir déjà atteint l'AGI ni l'exploitation autonome. Les capacités de long terme ne seront validées progressivement qu'après mise en place des frontières d'Evidence, de permissions, de budget, d'approbation et de rollback. -## 🔗 Projets connexes +## 🚢 Déploiement Preview -| Projet | Description | -|------|------| -| [One API](https://github.com/songquanpeng/one-api) | Licence MIT | -| [New API](https://github.com/QuantumNous/new-api) | Licence AGPLv3 | -| [Midjourney-Proxy](https://github.com/novicezk/midjourney-proxy) | Licence Apache-2.0 | -| [Suno API](https://github.com/Suno-API/Suno-API) | Licence MIT | +Les étapes suivantes servent aux tests et à la validation progressive de la version Preview. Pour la production, utilisez une version stable et conservez la même procédure de vérification et de retour arrière. -### Outils associés +Docker Compose est recommandé : -| Projet | Description | -|------|------| -| [max-api-key-tool](https://github.com/MAX-API-Next/MAX-API-key-tool) | Outil de consultation de quota de clés | -| [max-api-horizon](https://github.com/MAX-API-Next/MAX-API-horizon) | Édition MAX API optimisée hautes performances | +```bash +MAX_API_VERSION=v2.0.0-smartops.pre1 +MAX_API_COMMIT=b7096156549edc930ca244891afb1ba5632dbe8f +git clone --branch "$MAX_API_VERSION" --depth 1 https://github.com/MAX-API-Next/MAX-API.git +cd MAX-API ---- +actual_commit="$(git rev-parse HEAD)" +if [ "$actual_commit" != "$MAX_API_COMMIT" ]; then + echo "Unexpected commit: $actual_commit" >&2 + exit 1 +fi -## 📚 Documentation et support - -| Ressource | Lien | -|------|------| -| Documentation officielle | [MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) | -| Signalement | [GitHub Issues](https://github.com/MAX-API-Next/MAX-API/issues) | -| Dernières versions | [Releases](https://github.com/MAX-API-Next/MAX-API/releases) | -| DeepWiki | [Ask DeepWiki](https://deepwiki.com/MAX-API-Next/MAX-API) | - -### Développements dérivés et remerciements à la communauté - -Si vous développez une version dérivée de ce projet pour votre propre usage, vous pouvez afficher clairement la source du projet ou un remerciement à la communauté sur la page d'accueil, dans le pied de page ou sur la page « À propos », en choisissant l'une des options suivantes : - -- Ajouter le lien du projet : [MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) -- Remercier la communauté : [MAX-API-Next](https://github.com/MAX-API-Next) - -Exemple de code d'intégration frontend (React / Tailwind CSS ; conservez l'un ou l'autre élément selon vos besoins) : - -```tsx -

- Développé à partir de{' '} - - MAX-API-Next/MAX-API - {' '} - · Merci à la{' '} - - communauté MAX-API-Next - -

+# Modifier les mots de passe de base de données et Redis, puis configurer les secrets dans docker-compose.yml +docker compose up -d ``` -En respectant l'une des exigences d'affichage ci-dessus et en maintenant le lien clairement visible, vous obtenez automatiquement une licence commerciale temporaire pour ce projet, sans demande ni approbation supplémentaire. Cette licence n'est pas permanente et reste valable uniquement tant que l'exigence d'affichage est respectée. Sa période de validité et toute modification ultérieure sont régies par le dernier avis publié dans ce README ou par la communauté officielle. - -Ce projet est développé à partir de [One API](https://github.com/songquanpeng/one-api) et de [New API](https://github.com/QuantumNous/new-api). À ce stade, MAX API s'appuie sur ces bases pour renforcer ses capacités de passerelle d'API d'IA et de gouvernance, enrichir ses fonctionnalités et corriger les anomalies. Toute utilisation commerciale doit également respecter la licence MIT de One API et la licence AGPLv3 de New API, conformément au fichier `LICENSE` actuellement publié par chaque projet en amont. La licence commerciale temporaire fournie par ce projet ne remplace ni ne supprime aucune obligation liée aux licences open source des projets en amont. +### Vérifications de déploiement -Si l'exigence d'affichage n'est plus respectée, ou si la licence temporaire expire, est modifiée ou prend fin par avis, vous devez respecter l'AGPLv3 ou obtenir une autorisation écrite distincte. Pour une licence commerciale à long terme, contactez : maxapi@max-api.ai. +| Composant | Recommandation | +|---|---| +| Base de données | Utiliser une version de MySQL ou PostgreSQL toujours couverte par le support de sécurité du fournisseur (MySQL 8.4 LTS et PostgreSQL 14+ recommandés), avec sauvegarde et reprise configurées | +| Cache | Le cache mémoire convient à un nœud ; Redis est recommandé pour plusieurs nœuds | +| Point d'entrée | Configurer un reverse proxy HTTPS, des limites de taille et une politique de réseau de confiance | +| Secrets | Définir explicitement un `SESSION_SECRET` aléatoire ; `CRYPTO_SECRET` est une surcharge facultative qui reprend `SESSION_SECRET` s'il est absent et doit être partagé entre Redis ou plusieurs nœuds lorsqu'il est défini | +| Nœuds | Donner à chaque nœud un `NODE_NAME` stable et unique | +| Journaux | Configurer `LOG_SQL_DSN`, nettoyage et rétention selon les exigences de conformité et d'exploitation | -Contributions de code, documentation, expériences d'adaptation fournisseur et pratiques de déploiement sont bienvenues. +Les déploiements multi-nœuds doivent partager `SESSION_SECRET`, tout en utilisant un `NODE_NAME` différent par nœud. `CRYPTO_SECRET` est une surcharge facultative qui reprend `SESSION_SECRET` s'il est absent ; s'il est défini explicitement, utilisez la même valeur sur chaque nœud. Utilisez `LOG_SQL_DSN` pour une base de journaux séparée et activez `ERROR_LOG_ENABLED` lorsque les statistiques de performance des erreurs sont nécessaires. Consultez la [documentation](https://docs.max-api.ai) pour toutes les variables d'environnement et les instructions de build depuis les sources. ---- +## 🤝 Origines du projet, remerciements et développements dérivés -## 📜 Licence +MAX API poursuit le travail open source de [One API](https://github.com/songquanpeng/one-api) et [New API](https://github.com/QuantumNous/new-api). Nous remercions les projets amont, leurs contributeurs et toutes les personnes qui apportent adaptateurs, tests, documentation, traductions et rapports d'incident. -Ce projet est sous [GNU Affero General Public License v3.0 (AGPLv3)](./LICENSE). +Conformément au fichier [NOTICE](./NOTICE) et à la section 7 de l'AGPLv3, toute version modifiée qui présente une interface utilisateur doit conserver tous les éléments suivants dans un emplacement À propos, juridique, de pied de page ou d'attribution clairement visible : -Outre la licence AGPLv3 par défaut, les projets dérivés à usage propre qui respectent les conditions « Développements dérivés et remerciements à la communauté » ci-dessus reçoivent automatiquement la licence commerciale temporaire et non permanente qui y est décrite. Cette licence temporaire ne couvre que les ajouts et modifications que les responsables du projet MAX API sont en droit de concéder ; elle n'inclut ni ne remplace les licences des projets en amont tels que One API et New API. +- Un lien vers le projet MAX API d'origine : [MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) +- L'attribution exacte du NOTICE de MAX API : `Frontend design and development by MAX API contributors.` +- Un lien vers le projet amont New API : [QuantumNous/new-api](https://github.com/QuantumNous/new-api) +- L'attribution exacte du NOTICE de New API : `Frontend design and development by New API contributors.` +- Une mention explicite des modifications avec une date pertinente -Si vous modifiez le projet et le fournissez aux utilisateurs via le réseau, comprenez et respectez les obligations AGPLv3 de disponibilité du code source. Pour coopération commerciale, institutionnelle ou autres questions de licence : maxapi@max-api.ai. +Un remerciement à la [communauté MAX-API-Next](https://github.com/MAX-API-Next) peut être ajouté, mais il ne remplace ni les liens obligatoires vers les projets, ni les attributions exactes, ni le marquage des modifications. ---- +Le respect continu de ces exigences d'affichage et du NOTICE accorde automatiquement une licence commerciale temporaire non perpétuelle, sans demande ni approbation séparée. Cette autorisation supplémentaire couvre uniquement les éléments que les responsables du projet MAX API ont le droit de licencier et ne dispense pas des obligations de l'AGPLv3, de One API, de New API ou des autres projets amont. Les conditions les plus récentes sont celles du README officiel et des annonces de la communauté. -## 🌟 Historique des étoiles +## 📜 Licence -
+Ce projet est distribué sous la [GNU Affero General Public License v3.0 (AGPLv3)](./LICENSE). -[![Star History Chart](https://api.star-history.com/svg?repos=MAX-API-Next/MAX-API&type=Date)](https://star-history.com/#MAX-API-Next/MAX-API&Date) +La licence commerciale temporaire couvre uniquement les ajouts et modifications que les responsables de MAX API ont le droit de licencier. Elle n'inclut, ne remplace et n'annule pas les obligations de licence de One API, New API ou d'autres projets amont. L'usage commercial doit également respecter la licence MIT de One API, la licence AGPLv3 de New API et les conditions de licence actuelles de chaque projet amont. -
+Si vous modifiez ce projet et le fournissez à des utilisateurs via un réseau, veuillez comprendre et respecter les obligations de mise à disposition du code source prévues par l'AGPLv3. Pour une licence commerciale de long terme, une coopération institutionnelle ou toute question de licence, contactez maxapi@max-api.ai. --- @@ -684,9 +354,9 @@ Si vous modifiez le projet et le fournissez aux utilisateurs via le réseau, com ### 💖 Merci d'utiliser MAX API -Si ce projet vous aide, pensez à lui donner une ⭐ Star. +Si ce projet vous aide, pensez à lui attribuer une ⭐ Star, suivre les Releases, signaler une Issue reproductible ou rejoindre la communauté MAX-API-Next. -**[Documentation officielle](https://github.com/MAX-API-Next/MAX-API)** • **[Issues](https://github.com/MAX-API-Next/MAX-API/issues)** • **[Releases](https://github.com/MAX-API-Next/MAX-API/releases)** +**[Dépôt du projet](https://github.com/MAX-API-Next/MAX-API)** • **[Contribuer](https://github.com/MAX-API-Next/MAX-API/issues)** • **[Dernières versions](https://github.com/MAX-API-Next/MAX-API/releases)** • **[Communauté MAX-API-Next](https://github.com/MAX-API-Next)** Built with ❤️ by MAX-API-Next diff --git a/README.ja.md b/README.ja.md index 909493b8..e369fcf0 100644 --- a/README.ja.md +++ b/README.ja.md @@ -1,10 +1,14 @@ -
+# MAX API -![max-api](/web/default/public/logo.png) +
-# MAX API +![MAX API](./web/default/public/logo.png) + +**AGI アプリケーション時代に向けた AI Models and Agents governance、インテリジェント運用、オープンコラボレーション基盤** + +**MAX API 2.0：インテリジェント運用の時代へ · 統一モデルゲートウェイから AGI ネイティブなガバナンス／運用基盤へ** -🍥 **AI モデルガバナンス、AgentOps、AGI アプリケーションサービス基盤** +[MAX API 2.0 Preview リリースノートを見る](https://github.com/MAX-API-Next/MAX-API/releases/tag/v2.0.0-smartops.pre1)

简体中文 | @@ -15,689 +19,334 @@

- licensereleasedockerGoReportCard + + license + + release + + docker + + GoReportCard +

- 位置づけ • - リリースチャネル • - ガバナンス • - 利用シーン • + ⭐ Star を付ける • + 💬 コミュニティに参加 • + 📚 ドキュメント • + 🚀 リリース +

+ +

+ コミュニティ • クイックスタート • - 機能 • - 設定 • - アーキテクチャ • - モデルと API • - デプロイ • - FAQ • - ライセンス + MAX API の価値 • + AGI 技術方針 • + 現在の機能 • + SmartOps • + Preview デプロイ

--- -## 📝 プロジェクト説明 - -MAX API は、研究機関と大学に所属する AGI 愛好者によって立ち上げられ、長期的に保守・運営されている AI モデルガバナンス、AgentOps、アプリケーションサービス基盤プロジェクトです。開発者、研究者、チーム、組織に対して、安定して再利用可能なサービスレイヤーを提供します。AI アプリケーションが実運用に入ると、モデル数の増加、上流 API の頻繁な変更、Agent の呼び出しチェーンの長大化、コストと監査の負担増加が発生します。MAX API は、アプリケーション、Agent、ユーザー、組織、上流モデルサービスの間に、アクセス、認証、ルーティング、課金、可観測性、ガバナンスの統一レイヤーを提供します。 - -実運用では、MAX API は単なるリクエスト転送ではありません。AI-ready アプリケーションと Agent ワークロード向けの運用可能なゲートウェイとして、プロトコル正規化、プロバイダー差分、トラフィック集中、長時間ストリーミング、大きなリクエストボディ、複数ノードキャッシュ、コスト監査、性能観測を同じガバナンス境界にまとめます。 - -継続的に注力する領域： - -- **AI モデルガバナンス**：OpenAI、Azure OpenAI、AWS Bedrock、Vertex AI、Ollama、および DeepSeek、Qwen / Alibaba Cloud Model Studio、Zhipu GLM、Kimi、Doubao / Volcano Engine、Tencent Hunyuan、Baidu ERNIE / Qianfan、iFlytek Spark、MiniMax、01.AI、SiliconFlow などのモデル更新、API 変更、パラメータ差分、価格ルール、タスクプロトコルを継続的に追跡します。Dify、RAGFlow、Kling、Seedance などのアプリケーション・マルチモーダルエコシステムも対象です。 -- **AI Agent ガバナンス / AgentOps**：Agent、ワークフロー、ツール呼び出しのシーンに対して、トークン管理、モデルアクセス制御、呼び出しトレース、コスト帰属、障害診断、ログ監査を強化します。 -- **チャネル設定ガバナンス**：チャネル作成・編集画面で、`chat/completions`、`responses`、`embeddings`、`rerank`、`video tasks`、model discovery などの能力を示すマトリクスと設定バリデーションを提供し、Base URL、JSON、Vertex AI リージョン、Codex 認証情報、動画タスクプレースホルダーなどのリスクを事前に検出します。 -- **運用最適化とコストガバナンス**：チャネルルーティング、失敗時 retry、レート制限、事前課金、失敗時返金、ログ可観測性、コスト統計、運用分析を継続的に改善します。token 系のシーンでは式ベース課金と統一 JSON 設定、動画などの非同期タスクではパラメータ化された rate-card を利用できます。 - -> [!IMPORTANT] -> - 公開向けに生成 AI サービスを提供する場合、利用者は管轄地域の規制に従い、届出、許認可、コンテンツ安全、本人確認、ログ保存、税務、決済、上流認可などを自ら完了する必要があります。 -> - ログ監査やコンテンツ保存などの機微な機能は、法的根拠、明確な通知、権限分離、データ安全対策がある場合にのみ有効化してください。 -> - MAX API はモデルと Agent ワークロードのゲートウェイガバナンスレイヤーです。上流モデルアカウント、API Key、基盤モデル学習機能は提供せず、Dify、LangChain、MCP Server などの Agent オーケストレーション / アプリケーション開発フレームワークを置き換えるものでもありません。 - ---- - -## 🚦 リリースチャネル - -現在の MAX API リリースは、正式版と Preview プレビュー版に分かれています。Preview 版では新機能や修正を先行公開し、コミュニティと運用者が実環境で互換性、安定性、セキュリティを検証できるようにします。正式版は、対応する Preview 版が 1 週間安定稼働した後に公開され、本番環境のアップグレードリスクを抑え、システムの安全性と信頼性を高めます。 - -本番環境では正式版を優先して利用してください。新機能、修正、互換性変更を早期に検証する場合は、テスト環境またはカナリア環境で Preview 版を使用し、アップグレード前にデータベースバックアップとロールバック手順を準備してください。 - ---- - -## 🎯 プロジェクトの位置づけ - -AGI アプリケーション時代において、MAX API はオープンな AI モデルガバナンスと AI Agent ガバナンス基盤に注力し、開発者と組織が AI アプリケーションと Agent ワークロードを安定運用するためのサービス、ガバナンス、運用レイヤーを構築します。 - -- **モデルガバナンスプレーン**：モデル入口、チャネル、プロバイダー、プロトコル形式、モデルマッピング、価格ルール、タスクプロトコル、マルチモーダル API を統一管理します。 -- **AgentOps コントロールプレーン**：Agent フレームワークを置き換えるのではなく、ゲートウェイ層でトークン管理、モデルアクセス制御、呼び出しログ、コスト追跡、障害診断、運用分析を提供します。 -- **チャネル設定プレーン**：能力マトリクス、フォーム検証、モデル発見、プロトコルテンプレートによって、上流チャネル追加や非標準 API の保守における設定ミスを減らします。 -- **プロトコル・プロバイダー適応レイヤー**：海外公式 API、中国国内モデルプラットフォーム API、OpenAI-compatible / 非標準 API の変化を追跡し、安定したアプリケーション側インターフェースへ正規化します。 -- **コスト、クォータ、信頼性ガバナンス**：チャネルルーティング、重み付き分配、retry、レート制限、事前課金、失敗時返金、式ベース課金、固定価格、タスク rate-card、倍率課金、利用統計をサポートします。 -- **性能とスケーラビリティガバナンス**：Redis / メモリキャッシュ、モデルリクエスト制限、ストリーミング timeout、大きな応答バッファ、リクエストボディ上限、ディスクキャッシュ、Pyroscope profiling、graceful shutdown により、単一ノードから複数ノードまで安定運用を支えます。 -- **組織運用・監査レイヤー**：チーム、研究機関、企業、コミュニティ向けに、ユーザー管理、グループ管理、プライベートデプロイ、データ保持、監査、継続運用最適化を提供します。 -- **再利用可能なガバナンステンプレート**：チャネルテンプレート、タスクプロトコルテンプレート、価格設定、デプロイ実践、運用ノウハウを蓄積します。 - ---- - -## 🧠 ガバナンスフレームワーク +MAX API は、アプリケーションや Agent と上流モデルサービスの間に位置する、統一モデルゲートウェイ、ガバナンス制御プレーン、運用エントリーポイントです。MAX-API-Next コミュニティは、実践的な AGI エンジニアリングを中心に本プロジェクトを継続的に開発し、開発者、研究者、企業のエンジニアリングチーム、大学の技術愛好者、オープンソース貢献者に協働の場を開いています。私たちの目標は、AGI アプリケーションが実際に必要とするモデル接続、権限、コスト、Evidence、インテリジェント運用、安全制御の基盤を構築することです。 -MAX API は、AI モデルと AI Agent の実行プロセスを、設定可能・観測可能・計算可能・監査可能なガバナンスフレームワークに組み込みます。 +AGI の領域で、私たちは **先進的かつ検証可能な技術を継続的に提供し、実際の本番課題をオープンなエンジニアリング能力へ変え、共同研究と貢献のためのコミュニティを築きます。** -| ガバナンス対象 | MAX API が提供する能力 | 目的 | -|----------|-------------------|------| -| モデル資産 | モデル一覧、モデルマッピング、モデルグループ、モデル制限、価格ルール、マルチモーダル API 管理 | どのモデルがあり、誰が使え、どう課金され、どう切り替えるかを把握する | -| 上流チャネル | プロバイダーチャネル、重み、グループ、状態、キー、Base URL、パス上書き、能力マトリクス、設定検証、モデル発見、失敗時 retry | 単一プロバイダー障害、値上げ、制限、設定ミス、API 変更のリスクを下げる | -| プロトコル形式 | OpenAI Compatible、Responses、Claude Messages、Gemini、Realtime、汎用動画タスクプロトコルなど | アプリケーション側が各社の差分を直接負担しないようにする | -| Agent トークン | API Key、トークングループ、モデル範囲、クォータ、期限、アクセス制御 | Agent、ワークフロー、ツール呼び出しに独立・回収可能・制限可能な認証情報を割り当てる | -| 利用量とコスト | リクエストログ、利用統計、式ベース課金、段階課金 JSON、タスク rate-card、事前課金、失敗時返金 | コストをユーザー、グループ、トークン、モデル、チャネル、ノード単位に分解する | -| 非同期タスク | 動画タスク送信、ポーリング、状態マッピング、結果プロキシ、タスク課金 | 長時間・多状態・多プロバイダー形式のマルチモーダルタスクを統一管理する | -| 監査と安全 | 管理者側ログ監査、エラーログ、リクエスト制限、ストリーミング timeout、ログインと権限制御 | プライベートデプロイとコンプライアンス環境に制御可能な監査境界を提供する | -| 組織運用 | ユーザー、グループ、残高、決済、システム設定、ダッシュボード、運用設定 | チーム、研究機関、企業、コミュニティサービスの継続運用を支える | - ---- +## 🌐 MAX-API-Next コミュニティに参加 -## 🧩 利用シーン +MAX API は単なるコードリポジトリではありません。AI Models、Agents、AgentOps、AGI エンジニアリングを対象とした長期的なオープンコラボレーションです。モデルゲートウェイの運用、Agent の開発、新しいモデルの適応、評価とガバナンスの研究、ドキュメントや翻訳の改善など、どのような形でもコミュニティへの参加と貢献を歓迎します。 -- **組織内 AI モデルガバナンス基盤**：ユーザー、トークン、モデル、チャネル、グループ、権限、価格、請求を統一管理します。 -- **Agent アプリケーションの実行・ガバナンス基盤**：Agent、ワークフロー、ツール呼び出しに対して、安定したモデルゲートウェイ、トークン分離、コスト制御、観測、障害診断、監査基盤を提供します。 -- **中国国内モデル・マルチプロバイダー適応センター**：国内外モデル API と価格変化を追跡し、チャネル設定、モデルマッピング、パス上書き、プロトコルテンプレートで適応コストを下げます。 -- **マルチモーダルタスクガバナンス基盤**：テキスト、画像、動画、音声、embeddings、rerank、リアルタイム会話を統一的に接続し、非同期タスクの状態、結果プロキシ、課金を管理します。 -- **モデルコスト・Agent コスト会計基盤**：ユーザー、トークン、モデル、チャネル、グループ単位でクォータ、費用、請求、分析を行います。 -- **プライベート・コンプライアンス運用環境**：キー、データ、権限、ログ、監査、課金ポリシーを自主管理したいチームや組織に適しています。 +**コミュニティに参加すると、リリース、モデルやプロトコルの変更、デプロイの実践、トラブルシューティングの知見、共同開発の機会をより早く得られます。** ---- - -## 🚀 クイックスタート - -デフォルトでは SQLite を使用するため、ローカル評価に追加データベースは不要です。 - -> [!WARNING] -> SQLite はローカル評価、開発、小規模テスト専用です。本番環境での使用は推奨しません。同時リクエスト、複数インスタンス構成、大量のログ・使用量データ、データベース移行、バックアップ／リストア、長時間トランザクションでは、ロック競合、書き込み停止、移行の長時間化や失敗、可用性・データ保守上の問題が発生する可能性があります。本番環境では、信頼できるバックアップ／リカバリ計画とともに MySQL ≥ 5.7.8 または PostgreSQL ≥ 9.6 を使用してください。 - -```bash -# 1. イメージを取得 -docker pull cscitechtop/max-api:latest - -# 2. サービスを起動し、データを ./data に永続化 -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest - -# 3. コンソールにアクセス -# ブラウザで http://localhost:3000 を開く -``` - -本番デプロイでは Docker Compose を使用し、データベース、Redis、セッションシークレット、暗号化シークレット、ログディレクトリを明示的に設定してください。 - -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API - -# docker-compose.yml の DB / Redis パスワードと環境変数を必要に応じて変更 -docker compose up -d -``` - -> [!WARNING] -> 本プロジェクトを公開向け生成 AI サービスまたは API サービスとして運用する場合、上流認可、届出、コンテンツ安全、本人確認、ログ保存、税務、決済、ユーザー規約などを先に完了してください。 - ---- - -## ✨ 主な機能 - -### AI モデルガバナンス - -| 機能 | 説明 | -|------|------| -| 統一モデル入口 | OpenAI-compatible、Responses、Claude Messages、Gemini、Realtime などを単一ゲートウェイで提供 | -| マルチプロバイダーモデルプール | OpenAI、Azure、Claude、Gemini、AWS Bedrock、Vertex AI、Ollama、および DeepSeek、Qwen、Zhipu GLM、Kimi、Doubao、Hunyuan、ERNIE、iFlytek Spark、MiniMax、01.AI、SiliconFlow などを継続適応 | -| 上流エコシステム適応 | Codex、Dify、RAGFlow、Kling、Seedance などのアプリケーション、Agent、マルチモーダルプラットフォームをガバナンス対象化 | -| モデルマッピングとアクセス範囲 | チャネルごとのモデル一覧、マッピング、ユーザーグループ、トークングループ、モデル制限 | -| チャネル能力マトリクス | `chat/completions`、`responses`、`Claude Messages`、`Gemini native`、`embeddings`、`images`、`audio`、`rerank`、`video tasks`、`model discovery` を表示 | -| チャネル設定検証 | API Key、モデル一覧、Base URL、JSON、Vertex AI リージョン、Codex 認証情報、モデル発見、動画タスクパスを保存前に検証 | -| マルチモーダル治理 | chat、images、video、audio、embeddings、rerank、realtime と非同期動画タスクを管理 | -| 汎用動画タスクプロトコル | 送信、問い合わせ、進捗、状態マッピング、エラー、結果 URL のパスを統一設定。body の透過送信と書き換えは既存のチャネル設定を利用します。既定は `/v1/videos/create` と `/v1/videos/{task_id}` | -| プロトコル変換とカスタム上流 | OpenAI Compatible、Responses、Chat Completions、Claude Messages、Gemini 間の変換、合法的に認可された上流 URL、パス上書き、タスク解析ルール | - -### AI Agent ガバナンス / AgentOps - -| 機能 | 説明 | -|------|------| -| Agent トークン分離 | Agent、ワークフロー、プラグイン、ツール呼び出し、ユーザーごとに独立 API Key を作成 | -| モデルアクセス制御 | ユーザー、トークン、グループ、モデル制限、チャネルポリシーで利用可能モデル・チャネル・クォータを制御 | -| 呼び出しチェーン観測 | リクエストログ、利用統計、チャネル命中、遅延、エラー、retry 情報 | -| コスト帰属 | モデル、チャネル、ユーザー、グループ、トークン、ノード単位でコストと利用量を集計 | -| 管理者監査 | プライベートデプロイで管理者側ログ監査を有効化可能。通常ユーザーログ API は管理者専用フィールドを除外 | -| 運用ダッシュボード | 管理者向け統計、ユーザー管理、チャネル管理、システム設定、運用分析 | - -### コスト、課金、信頼性ガバナンス - -**モデル価格式** - -- **1 行の式 = 1 つの token モデルの完全な価格ルール**：段階価格、cache hit、画像 / 音声 token、時間帯割引、リクエストヘッダーやパラメータによる動的加算を 1 行で表現できます。 -- **価格は実価格に近い形で管理**：係数を「USD / 百万 token」として入力できます。`p * 2.5` は入力 100 万 token あたり 2.5 USD を意味します。従来の倍率モードも互換です。 -- **ビジュアル + 生式編集**：価格と条件をフォームで入力することも、式を直接編集することもできます。 -- **統一 JSON 一括管理**：`Tiered billing JSON` で複数モデルの `{ enabled, expr }` を管理し、保存時に `billing_mode` と `billing_expr` を同期更新します。 -- **token 自動正規化**：上流形式と式で使用される変数に応じて cache、画像、音声などを分離し、二重課金を防ぎます。 - -**タスク課金、従来課金、信頼性** - -- 動画などの非同期タスクに対して、モデル、`vendor`、時間、品質、音声、動画入力などに基づく rate-card 課金をサポートします。`task_billing_setting.rate_cards` で Sora、Veo、Seedance、Kling などを `vendor` ごとに管理できます。 -- 従量課金、回数課金、cache hit、モデル倍率、グループ倍率、チャネル倍率に対応します。 -- 事前課金、失敗時返金、例外処理、消費ログをサポートします。 -- 重み付きチャネルルーティング、失敗時 retry、無効チャネル回避、モデルレベルルーティングをサポートします。 -- Redis キャッシュとメモリキャッシュにより、単一ノード・複数ノード構成に対応します。 - -### 性能とスケーラビリティガバナンス - -| 機能 | 説明 | -|------|------| -| キャッシュと複数ノード拡張 | 単一ノードではメモリキャッシュ、複数ノードでは Redis を利用できます。ユーザー、トークン、チャネル affinity、クォータ関連キャッシュで DB 読み取りを減らし、`SESSION_SECRET`、`CRYPTO_SECRET`、`NODE_NAME` によりセッション、暗号化、ログ帰属を揃えます | -| レート制限と容量保護 | グローバル API / Web、重要 endpoint、検索、モデルリクエスト、グループ別モデルリクエスト quota の制限をサポートし、Redis またはメモリカウンターを利用できます | -| ストリーミングと大きなリクエスト制御 | `STREAMING_TIMEOUT`、`STREAM_SCANNER_MAX_BUFFER_MB`、`MAX_REQUEST_BODY_MB`、`MAX_FILE_DOWNLOAD_MB` で長時間 stream、大きな SSE 行、解凍後リクエストボディ、リモートファイル download を制御します | -| リレー接続調整 | `RELAY_TIMEOUT`、`RELAY_IDLE_CONN_TIMEOUT`、`RELAY_MAX_IDLE_CONNS`、`RELAY_MAX_IDLE_CONNS_PER_HOST` で上流 HTTP timeout と connection pool を調整できます | -| ディスクキャッシュと性能観測 | 性能設定で大きなリクエストボディ向けディスクキャッシュ、閾値、容量を設定できます。運用 endpoint で確認 / クリアでき、Pyroscope で CPU、メモリ、goroutine、mutex、block profile を収集できます | -| Graceful shutdown とデータ保存 | `SHUTDOWN_TIMEOUT_SECONDS` と `QUOTA_DATA_CACHE_SAVE_TIMEOUT_SECONDS` により、可能な範囲で HTTP 処理を閉じ、クォータキャッシュを保存してから終了します | - -### セキュリティと組織管理 - -- JWT、WebAuthn/Passkeys、OAuth、OIDC、Telegram、Discord、LinuxDO などのログイン方式をサポートします。 -- 管理者、通常ユーザー、グループ、トークン、モデルアクセス制御をサポートします。 -- リクエストボディサイズ制限、ストリーミング timeout、エラーログ、稼働状態チェックをサポートします。 -- 複数ノード構成で統一セッションシークレット、暗号化シークレット、Redis 共有キャッシュを利用できます。 - ---- - -## 🆚 なぜゲートウェイを使うのか - -| 観点 | 各社公式 SDK / API に直接接続 | MAX API ゲートウェイ経由 | -|------|------------------------|-------------------| -| モデル接続 | プロバイダーごとに SDK、認証、パラメータが異なる | 統一モデル入口で、一度の接続から複数モデルを再利用 | -| モデルガバナンス | モデル一覧、価格、権限、チャネルが各平台に分散 | モデル、チャネル、マッピング、グループ、クォータ、価格を統一管理 | -| Agent アクセス | Agent が上流 Key を直接保持し、回収や制限が難しい | Agent ごとに独立トークンを割り当て、モデル・クォータ・期限・グループを制限 | -| プロトコル差分 | Claude、Gemini、Responses などをアプリ側で吸収 | ゲートウェイがプロトコル変換とプロバイダー適応を担当 | -| 障害処理 | retry、fallback、エラー正規化をアプリ側で実装 | チャネル失敗時 retry、重み付きルーティング、エラー処理を内蔵 | -| 性能と拡張 | timeout、レート制限、接続 pool、cache をアプリ側で処理 | ゲートウェイが streaming timeout、リクエスト制限、Redis / メモリ cache、接続 pool 調整、性能観測を集約 | -| コスト統計 | 請求が各平台に分散し、ユーザーや Agent への帰属が難しい | クォータ、課金、利用統計、消費ログを統一し、トークンとモデル単位で帰属可能 | -| 監査境界 | アプリ側ログが分散し、権限・保持ポリシーが不統一 | 管理者側統一監査入口、通常ユーザーには管理者専用フィールドを除外 | -| プライベート化 | Key、ログ、課金ポリシーが分散 | 自己ホストで Key、データ、ログ、ポリシーを掌握 | - ---- - -## 🧭 アーキテクチャ概要 - -MAX API は階層型アーキテクチャを採用しています。アプリケーション、SDK、Agent のリクエストは統一入口から入り、ルーター、ミドルウェア、コントローラー、サービス層を経由し、最後に relay 層が対応する上流プロバイダーへ適応します。データ層とキャッシュ層は、モデルガバナンス、Agent トークン管理、課金、ログ、監査、タスク状態の永続化と高速化を担います。 - -```mermaid -flowchart LR - Client[Client / SDK / Agent] --> Router[Router
Routing] - Router --> MW[Middleware
Auth · Rate Limit · Dispatch · Logs] - MW --> Ctrl[Controller
Request Handlers] - Ctrl --> Svc[Service
Model Governance · AgentOps · Billing Audit] - Svc --> Relay[Relay
Proxy / Protocol Conversion] - Relay --> Adapters[Channel Adapters
OpenAI · Claude · Gemini · Chinese Platforms · Custom Upstreams] - Adapters --> Upstream[(Upstream Model Services)] - Svc --> Model[Model
GORM] - Model --> DB[(SQLite · MySQL · PostgreSQL)] - Svc --> Cache[(Redis · In-memory Cache)] -``` - -### ディレクトリ構成 - -| ディレクトリ | 役割 | -|------|------| -| `router/` | HTTP ルーティング。API、relay、dashboard、web 入口を含む | -| `controller/` | リクエストハンドラー。パラメータ解析、認証後の業務入口、レスポンス整形 | -| `service/` | モデル治理、AgentOps、ログ、課金、監査、タスク、チャネル、システム設定などの業務ロジック | -| `model/` | GORM ベースのデータモデルと DB アクセス。SQLite、MySQL、PostgreSQL に対応 | -| `relay/` | AI API relay、プロトコル変換、プロバイダー適応 | -| `relay/channel/` | openai、claude、gemini、aws などのプロバイダーアダプター | -| `middleware/` | 認証、レート制限、CORS、ログ、リクエスト分配、コンテキスト処理 | -| `setting/` | モデル価格、タスク課金、運用、システム、セキュリティ、性能設定 | -| `common/` | JSON、暗号化、Redis、レート制限、環境変数などの共通ユーティリティ | -| `dto/` / `types/` | リクエスト、レスポンス、エラー、relay 形式の型定義 | -| `constant/` | API 種別、チャネル種別、コンテキストキーなどの定数 | -| `i18n/` / `oauth/` / `pkg/` | バックエンド i18n、OAuth 実装、内部パッケージ | -| `web/` | フロントエンドテーマコンテナ。既定テーマは `web/default/` | - -### 技術スタック - -| レイヤー | 技術 | -|------|------| -| Backend | Go 1.25+, Gin, GORM v2 | -| Frontend | React 19, TypeScript, Rsbuild, Base UI, Tailwind CSS | -| パッケージ管理 | Bun workspace | -| データベース | SQLite / MySQL ≥ 5.7.8 / PostgreSQL ≥ 9.6 | -| キャッシュ | Redis + メモリキャッシュ | -| 認証 | JWT, WebAuthn/Passkeys, OAuth, OIDC | - ---- - -## 🤖 AI モデルとインターフェース対応 +

+ QQ グループ：950126533 • + WeChat グループ：MAX-API を検索 +

-> 実際に利用可能なモデルは、上流認可、チャネル設定、モデルマッピング、プロバイダーサポートに依存します。MAX API はこれらの能力を統一ガバナンスに取り込むものであり、上流モデルサービス自体を提供するものではありません。 +| コミュニティ窓口 | 用途 | +|---|---| +| [MAX-API-Next GitHub](https://github.com/MAX-API-Next) | コミュニティプロジェクト、技術方針、オープンコラボレーションをフォロー | +| [MAX API Issues](https://github.com/MAX-API-Next/MAX-API/issues) | 再現可能な問題、改善提案、互換性の変化を共有 | +| [MAX API Releases](https://github.com/MAX-API-Next/MAX-API/releases) | 正式版と Preview 版の更新を確認 | +| [Ask DeepWiki](https://deepwiki.com/MAX-API-Next/MAX-API) | コードベースをすばやく検索・理解 | +| 技術・エコシステム連携 | `maxapi@max-api.ai` まで連絡 | -| 種別 | 説明 | -|------|------| -| OpenAI-Compatible | Chat Completions、Embeddings、Images、Audio などの互換 API | -| OpenAI Responses | Responses 形式のリクエスト、relay、Responses ↔ Chat Completions 互換変換 | -| Claude Messages | Claude Messages と OpenAI-compatible 形式の変換 | -| Google Gemini | Gemini chat、text、`/v1/responses` 互換変換 | -| Azure OpenAI | Azure OpenAI と Realtime 関連 API | -| AWS Bedrock | Bedrock Runtime モデル接続 | -| 上流平台・アプリケーションエコシステム | AWS、Azure、Vertex、Ollama、Codex、Dify、RAGFlow、Kling、Seedance など | -| 中国国内モデル・平台 | DeepSeek、Qwen / Alibaba Cloud Model Studio、Zhipu GLM、Kimi、Doubao / Volcano Engine、Tencent Hunyuan、Baidu ERNIE / Qianfan、iFlytek Spark、MiniMax、01.AI、SiliconFlow など | -| `rerank` | Cohere、Jina などの rerank モデル。RAG や Agent 検索チェーンに利用 | -| Midjourney / Suno / Dify | 画像、音楽、ワークフローなどのサービス適応 | -| 動画タスク API | `/v1/videos/create`、`/v1/videos/{task_id}` による送信、body 透過送信またはパラメータ上書き、ポーリング、状態マッピング、結果プロキシ、パラメータ化課金 | -| カスタム上流 | 認可済み上流 URL、プロトコル適応、Responses / Chat 変換、パス上書き、状態マッピング、エラー経路、結果解析 | +### 求めている貢献者 -### 主な対応インターフェース +- **モデル／プロトコル貢献者**：新しいモデルやプロバイダー、Reasoning、ツール呼び出し、マルチモーダルタスクプロトコルの適応。 +- **Agent／アプリケーション開発者**：Dify、RAGFlow、Codex、MCP、ワークフロー、研究 Agent の接続・ガバナンス事例の共有。 +- **信頼性／セキュリティエンジニア**：複数データベースのテスト、非同期タスク復旧、精算安全性、キャッシュ整合性、権限境界の強化。 +- **ドキュメント／コミュニティ貢献者**：デプロイガイド、FAQ、事例、翻訳、再現可能な実験、新規貢献者向けガイドの改善。 +- **研究者／評価開発者**：Evidence、Evaluator、Detector、Runbook、制御された自律性の設計。
-インターフェースカテゴリを見る - -- Chat：`/v1/chat/completions` -- Responses：`/v1/responses` -- Images：`/v1/images/*` -- Audio：`/v1/audio/*` -- Video：`/v1/videos/*` -- Embeddings：`/v1/embeddings` -- Rerank：`/v1/rerank` -- Realtime conversation：OpenAI Realtime 互換 API -- Claude Messages：Claude ネイティブ形式入口 -- Gemini：Google Gemini 形式入口 +共同開発の領域、原則、参加方法を見る -
+| 共同開発領域 | 貢献例 | +|---|---| +| モデル／プロバイダーエコシステム | モデル・プロトコルアダプター、互換性テスト、モデル一覧や廃止情報、チャネル設定テンプレート | +| AgentOps と AGI アプリケーションガバナンス | Agent 接続例、トークンと権限の境界、コストガバナンス、運用プラクティス | +| SmartOps と Evidence | 匿名化した障害事例、メトリクス定義、アラートルール、データ品質説明、診断・評価手法 | +| 信頼性、課金、セキュリティ | 冪等精算、非同期復旧、複数データベース回帰テスト、キャッシュ整合性、高リスク操作の検証 | +| ドキュメント、チュートリアル、国際化 | デプロイ、アーキテクチャ、FAQ、事例、翻訳、新規貢献者ガイド | -### Reasoning Effort 対応 +可能な限り、最小再現、バージョン、環境、匿名化したログ、またはテスト証拠を提供してください。プロトコル、データベース、ユーザー契約を変更する場合は、互換性、移行、ロールバック手順を明記してください。実際の API Key、顧客データ、決済の生データ、非公開ログ、許可されていないデータを送信しないでください。資金、セキュリティ、秘密情報、本番データ、自動実行に関わる貢献には、より厳格なテスト、独立レビュー、明確な責任者が必要です。 -
-モデル名の例を見る +次の方法から始められます： -- `o3-mini-high`, `o3-mini-medium`, `o3-mini-low` -- `gpt-5-high`, `gpt-5-medium`, `gpt-5-low` -- `claude-3-7-sonnet-20250219-thinking` -- `gemini-2.5-flash-thinking`, `gemini-2.5-flash-nothinking`, `gemini-2.5-pro-thinking`, `gemini-2.5-pro-thinking-128` -- Gemini モデル名に `-low`、`-medium`、`-high` を追加して推論強度を制御できます。 +1. 再現可能な問題、プロトコル差分、モデル互換性の変化を報告する。 +2. 既存 Issue に失敗テスト、複数データベースのケース、フロントエンド回帰、匿名化した Evidence を追加する。 +3. モデル／チャネル設定、デプロイ手順、FAQ、アーキテクチャ、翻訳を改善する。 +4. 匿名化した Agent 接続、コストガバナンス、SmartOps、プライベートデプロイの実践を共有する。 +5. 能力境界とリスクを明示した Evaluator、Detector、Runbook、制御された自律性の設計を提案する。
---- - -## 🔧 ガバナンス設定 - -### 推奨初期設定 - -1. デプロイ後、コンソールに入り管理者アカウントを作成または確認します。 -2. システム設定、ユーザー登録ポリシー、ログイン方式、安全制限を設定します。 -3. 上流チャネルを追加し、認可済み API Key、Base URL、モデル一覧、モデルマッピング、チャネル設定を入力します。 -4. 組織構造に応じて、ユーザーグループ、トークングループ、モデル制限、クォータ、価格ルールを設定します。 -5. アプリケーション、Agent、ワークフローごとに独立トークンを作成し、モデル範囲とクォータを設定します。 -6. retry、ログ記録、キャッシュ戦略、消費統計を設定します。 -7. 管理者側コンテンツ監査が必要な場合は、適法な前提で「System Settings → Security & Limits → Log Audit」を有効化し、「Record quota usage (Log Maintenance)」が有効であることを確認します。 - -### チャネル能力マトリクスと設定検証 - -チャネル作成・編集時、システムはチャネル種別に基づいて能力マトリクスとリアルタイム検証結果を表示します。`chat/completions`、`responses`、`embeddings`、`rerank`、`video tasks` などの技術名はそのまま表示し、説明で用途を補足します。 - -検証対象には、API Key 不足、モデル一覧空、Base URL / 追加設定不足、Base URL が `/v1` で終わる誤設定、JSON オブジェクト不正、Vertex AI の `default` リージョン不足、サービスアカウントキー不正、Codex の `access_token` / `account_id` 不足、未対応チャネルでのモデル発見有効化、動画タスク問い合わせパスの `{task_id}` / `{operation_name}` / `{upstream_task_id}` 不足などがあります。 - -### 汎用動画タスクプロトコル - -動画モデルプロバイダーは、パス、task ID、状態フィールド、進捗フィールド、エラーフィールド、結果 URL フィールドが異なることが多いです。MAX API はこの能力を汎用動画タスクプロトコルとして拡張し、OpenAI、Ali、Gemini、MiniMax、Vertex AI、VolcEngine、Kling、Jimeng、Vidu、Doubao Video、Sora などの動画タスクチャネルに適用します。 +関連ドキュメント：[MAX-API-Docs](https://github.com/MAX-API-Next/MAX-API-Docs)（デプロイ、設定、利用ガイド）。 -- **パス上書きのみ**：`submit_path` と `query_path` のみを設定し、公式レスポンスパーサーを継続利用します。 -- **完全プロトコル解析**：`task_protocol = "generic_video_task"` を設定し、task ID、状態、進捗、結果 URL、エラー、状態マッピングのパスを設定します。 -- **リクエスト body 処理**：汎用動画タスクプロトコルは個別の body 生成モードを持ちません。クライアント JSON をそのまま上流へ送る場合はチャネル設定の `Pass Through Body` を使い、フィールド書き換え、既定値、header 連動には既存の `Param Override` を使います。 +モデルプロバイダー、Agent／ワークフロープロジェクト、オープンソースコミュニティ、研究者、企業エンジニアリングチームとの技術協働を歓迎します。正式な提携、共同発表、機関名の使用には、双方の明示的な承認が必要です。 -既定パス： - -```json -{ - "task_protocol": "generic_video_task", - "task_protocol_config": { - "submit_path": "/v1/videos/create", - "query_path": "/v1/videos/{task_id}", - "task_id_path": "task_id", - "status_path": "status", - "progress_path": "progress", - "result_url_paths": ["result.primary_url", "result.urls.0", "data.result.primary_url", "url", "video_url", "download_url"], - "error_message_path": "error_message", - "status_map": { "queued": "QUEUED", "running": "IN_PROGRESS", "succeeded": "SUCCESS", "failed": "FAILURE" } - } -} -``` - -問い合わせパスは `{task_id}`、`{operation_name}`、`{upstream_task_id}` をサポートします。`{operation_name}` は Gemini / Vertex 形式の複数セグメント path を保持できます。動画コンテンツは `/v1/videos/{task_id}/content` でプロキシ取得でき、上流ドメインを隠したい場合は認証、SSRF 防御、許可ポート設定と組み合わせて利用してください。 - -### 課金 JSON メンテナンス - -- **Tiered billing JSON**：複数モデルの `{ enabled, expr }` を一括管理し、`billing_mode` と `billing_expr` を同期更新します。 -- **Task rate-card JSON**：`task_billing_setting.rate_cards` で非同期タスク課金ルールを管理し、`vendor` で Sora、Veo、Seedance、Kling などを分けます。 - -Seedance 2.0 などの動画モデルでは、解像度や動画入力などのリクエストパラメータを倍率または rate-card 課金に利用できます。透過送信またはパラメータ上書きを使う場合は、最終的に上流へ送るフィールドと課金フィールドを揃えてください。 - -```json -{ - "model-name": { - "enabled": true, - "expr": "len <= 200000 ? tier(\"standard\", p * 3 + c * 15) : tier(\"long_context\", p * 6 + c * 22.5)" - } -} -``` - -```json -{ - "vendor/model-name": { - "vendor": "kling", - "unit": "second", - "quantity_field": "duration", - "default_quantity": 5, - "strict": true, - "defaults": { "quality": "std", "has_audio": "false" }, - "rows": [{ "id": "std_no_audio", "match": { "quality": "std", "has_audio": "false" }, "unit_price": 0.6 }] - } -} -``` +> [!IMPORTANT] +> 一般向けに生成 AI サービスを提供する場合、運営者は管轄地域で求められる上流認可、届出・許可、コンテンツ安全、本人確認、ログ保存、税務、決済、利用規約などの義務を自ら履行する必要があります。ログ監査やコンテンツ保存は、法的根拠、明確な通知、権限分離、適切なデータセキュリティ対策がある場合にのみ有効化してください。 -### よく使う運用入口 +MAX API 管理コンソール -| 機能 | 説明 | -|------|------| -| チャネル管理 | 上流プロバイダー、モデルマッピング、重み、キー、プロトコルパス、状態、能力マトリクス、検証 | -| モデルと価格 | モデル一覧、価格、式ベース課金、段階課金 JSON、タスク rate-card JSON、表示情報 | -| トークン管理 | アプリケーション、Agent、ワークフロー、ツール、ユーザー向けアクセス token | -| ユーザー管理 | ユーザー、グループ、残高、権限、状態 | -| 利用ログ | 呼び出し、消費、遅延、エラー、チャネル命中、管理者可視の監査情報 | -| システム設定 | 安全制限、ログ監査、モデル価格、タスク課金、運用戦略、ログ保守、決済、サイト設定 | -| ダッシュボード | 総リクエスト、モデル利用、消費傾向、チャネル状態、Agent token コスト | +## 🧠 AGI に向けた技術方針 ---- +AGI アプリケーションは、単一モデル、単一プロトコル、単発リクエストだけに依存し続けることはありません。複数モデルにまたがる推論、ツール呼び出し、マルチモーダルタスク、長時間実行、コスト制約、本番 Evidence、回復可能な失敗処理が必要です。MAX API は、これらの検証可能なエンジニアリング課題から AI Models and Agents governance の基盤を構築します。 -## 🚢 デプロイ +| 技術方針 | 現在の基盤 | AGI アプリケーションへの価値 | +|---|---|---| +| マルチモデル／マルチプロトコル接続 | OpenAI Compatible、Responses、Claude Messages、Gemini、Realtime、マルチモーダルおよび非同期タスクプロトコル | モデルエコシステムが変化しても、アプリケーションと Agent に比較的安定した入口を提供 | +| 推論／ツールコンテキスト互換性 | Reasoning Effort、ツール定義、Tool Call、ツール応答の関連付け、マルチターンコンテキスト変換 | プロバイダー切り替え時の推論情報やツール意味論の損失を軽減 | +| ガバナンス制御プレーン | ユーザー、トークン、モデル範囲、グループ、ルーティング、レート制限、クォータ、価格、管理者権限 | Agent、環境、タスクごとに独立したアイデンティティ、アクセス、予算の境界を作成 | +| 回復可能な課金とタスクライフサイクル | 事前課金、最終精算、冪等記録、失敗時返金、非同期ポーリング、手動照合状態 | 長時間タスク、リトライ、障害ウィンドウでの重複請求、誤返金、追跡不能な結果を防止 | +| Evidence とインテリジェント運用 | ログ、エラー、リトライ、性能バケット、アクティブアラート、チャネル／モデル性能、精算証拠 | 診断、評価、将来の Agent 提案を、プロンプトだけでなく追跡可能な事実に基づかせる | +| セキュリティ／組織ガバナンス | Passkey、2FA、スコープ別再認証、セッション失効、監査、機密操作のレート制限 | 高リスク設定、認証情報、運用操作に明確な責任境界を保持 | +| 制御された自律性とエンジニアリング進化 | **長期ビジョン**：Policy、Budget、Approval、Shadow、Canary、Rollback、分離された Coding Workspace | 自動化を評価・制約・監査してから、低リスクの本番操作へ段階的に導入 | -### 要件 +### 技術原則 -| コンポーネント | 要件 | -|------|------| -| コンテナエンジン | Docker / Docker Compose | -| ローカルデータベース | SQLite。ローカル評価、開発、小規模テスト専用。Docker 利用時は `/data` をマウント | -| 本番データベース | MySQL ≥ 5.7.8 または PostgreSQL ≥ 9.6。信頼できるバックアップ／リカバリ計画を設定 | -| キャッシュ | 単一ノードはメモリキャッシュ、複数ノードは Redis 推奨 | -| フロントエンドビルド | Bun workspace。`web/package.json` と `web/bun.lock` を保持 | -| ソースビルド | `go.mod` に記載された Go バージョン（現在は Go 1.25.1+）とリポジトリ内の `go.sum` を使用。依存関係またはセキュリティ更新後は `go mod download`、`go mod verify` を実行してから再ビルド | +- **Evidence before Action**：診断、提案、自動操作の前に、検証可能な事実を確立する。 +- **Governance before Autonomy**：アイデンティティ、権限、予算、承認、監査、ロールバックを自律機能より先に整備する。 +- **One Billing Truth**：本番課金、クォータ、精算は単一の事実源を維持し、Agent やプラグインに第二の会計ロジックを作らない。 +- **Compatibility by Design**：SQLite、MySQL、PostgreSQL、複数プロバイダープロトコル、移植可能なアプリケーション契約を継続的にサポートする。 +- **Open Collaboration, Safe Boundaries**：プロトコルアダプター、テスト、ドキュメント、評価、ガバナンス設計を公開し、高リスクの本番、資金、秘密情報、リリース操作は明示的な承認下に置く。 -### 推奨環境変数 +### MAX API 2.0 の技術的ハイライト -
-よく使う環境変数を見る - -| 変数 | 説明 | 既定値 | -|--------|------|--------| -| `SESSION_SECRET` | セッションシークレット。複数ノードでは必須 | - | -| `CRYPTO_SECRET` | 暗号化シークレット。Redis または複数ノードでは必須 | - | -| `SQL_DSN` | データベース接続文字列 | - | -| `REDIS_CONN_STRING` | Redis 接続文字列 | - | -| `STREAMING_TIMEOUT` | ストリーミングレスポンス timeout 秒数 | `300` | -| `STREAM_SCANNER_MAX_BUFFER_MB` | ストリームスキャナーの 1 行最大バッファ。base64 画像などで調整 | `64` | -| `MAX_REQUEST_BODY_MB` | 解凍後リクエストボディ最大サイズ。超過時 `413` | `32` | -| `AZURE_DEFAULT_API_VERSION` | Azure API 既定バージョン | `2025-04-01-preview` | -| `ERROR_LOG_ENABLED` | エラーログスイッチ | `false` | -| `NODE_NAME` | 複数ノード時のログ識別と非同期タスク精算帰属に使うノード名 | - | -| `PYROSCOPE_URL` | Pyroscope サービス URL | - | -| `PYROSCOPE_APP_NAME` | Pyroscope アプリ名 | `max-api` | -| `PYROSCOPE_BASIC_AUTH_USER` | Pyroscope Basic Auth ユーザー名 | - | -| `PYROSCOPE_BASIC_AUTH_PASSWORD` | Pyroscope Basic Auth パスワード | - | -| `PYROSCOPE_MUTEX_RATE` | Pyroscope mutex サンプリング率 | `5` | -| `PYROSCOPE_BLOCK_RATE` | Pyroscope block サンプリング率 | `5` | -| `HOSTNAME` | Pyroscope ラベルのホスト名 | `max-api` | +- **Evidence-driven SmartOps**：リソースアラート、チャネル／モデル性能、データ品質状態、課金精算 Evidence を一つの運用入口に集約し、人によるレビューと実際の財務状態の境界を維持します。 +- **高度なモデルプロトコルへの継続対応**：Responses、Claude Messages、Gemini、Ollama における Reasoning、キャッシュキー、ペナルティパラメータ、ツール定義、マルチターン Tool Context の互換性を強化します。 +- **回復可能な課金／非同期タスク意味論**：冪等 settlement、永続 effect、タスク ID、明示的な pending/manual 状態により、異常リトライによる重複請求、誤返金、タスク消失を防ぎます。 +- **高リスク操作のスコープ別再認証**：Passkey、2FA、Telegram、API Token、セッション失効は scope-bound step-up verification を使用し、`session_generation` によって古いセッションを速やかに無効化します。 +- **複数データベース対応と継続的検証**：主要データパスは SQLite、MySQL、PostgreSQL に対応します。Go テスト、フロントエンド Bun テスト、TypeScript 型チェック、JSON ラッパールール、テストミラー同期がリリースゲートを構成します。 -
+## 💡 MAX API が必要な理由 -### Docker Compose +| 観点 | 複数プロバイダーへの直接接続 | MAX API を使用 | +|---|---|---| +| アプリケーション接続 | SDK、プロトコル、認証、エラー形式を個別に保守 | アプリケーション側は比較的安定した統一入口を使用 | +| モデル切り替え | コード、秘密情報、デプロイ設定を変更 | チャネル、モデルマッピング、グループ、ルーティングで調整 | +| 可用性 | 各アプリケーションがリトライと上流障害を処理 | 重み、優先度、失敗時リトライ、切り替えを集中設定 | +| 権限／秘密情報 | 認証情報がアプリケーションや環境変数に分散 | トークン、モデル範囲、クォータ、有効期限を集中管理 | +| コスト管理 | 複数社の請求が分散し帰属が困難 | ユーザー、トークン、モデル、チャネル、グループ別に集計 | +| トラブルシューティング | ログがプロバイダーごとに分散 | ゲートウェイでリクエスト、エラー、リトライ、レイテンシを統一観測 | -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API - -# docker-compose.yml を必要に応じて変更： -# - PostgreSQL / MySQL / Redis の既定パスワードを変更 -# - SESSION_SECRET、CRYPTO_SECRET、NODE_NAME を設定 -# - 本番ではリバースプロキシと HTTPS を設定 -docker compose up -d -``` +一言で表すと、**プロバイダーはモデルを提供し、Agent フレームワークはアプリケーションをオーケストレーションし、MAX API は統一アクセスとガバナンス境界を担います。** -### Docker コマンド +## 🚀 クイックスタート -**SQLite:** +ローカル環境ではデフォルトで SQLite を使用し、必要なのは Docker だけです： ```bash -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest -``` +MAX_API_IMAGE=cscitechtop/max-api:latest@sha256:006d5d86887a261baab4d71ec3797d429e3771a4836e5899734aee0e7f66f2ab -**MySQL:** +docker pull "$MAX_API_IMAGE" -```bash -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e SQL_DSN="root:123456@tcp(mysql:3306)/max-api" \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest +docker run --name max-api -d --restart always -p 127.0.0.1:3000:3000 -e TZ=Asia/Shanghai -v ./data:/data "$MAX_API_IMAGE" ``` -### ソースからイメージをビルド - -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API -docker build -t cscitechtop/max-api:latest . -``` + を開き、次の操作を行います： -> [!NOTE] -> `Dockerfile` はイメージビルド中に Go モジュールをダウンロードします。ホストで直接ビルドする場合、または依存関係 / セキュリティ更新後は、`go.mod` と `go.sum` を必ず一緒にコミットし、`go mod download && go mod verify` を実行してからバイナリまたはイメージを再ビルドしてください。ベースイメージを更新する必要がある場合は `docker build --pull --no-cache -t cscitechtop/max-api:latest .` を使用します。 +1. 管理者アカウントを作成または確認する。 +2. 正当な利用権限を持つ上流チャネルと API Key を追加する。 +3. アクセストークンを作成し、アプリケーションの Base URL を MAX API に向ける。 > [!TIP] -> フロントエンドは Bun workspace を使用します。ビルドコンテキストには `web/package.json`、`web/bun.lock`、`web/default/package.json` を保持してください。そうしないと `catalog:` 依存関係を解決できません。 - -### 複数ノードデプロイの注意 - +> 本番環境では正式版を使用してください。Preview 版はテストと段階的検証向けです。アップグレード前にデータベースをバックアップし、ロールバック手順を準備してください。 +> > [!WARNING] -> - 全ノードで同じ `SESSION_SECRET` を設定してください。異なるとログイン状態がノード間で一致しません。 -> - 共有 Redis を使用する場合は、全ノードで同じ `CRYPTO_SECRET` を設定してください。異なると暗号化データを復号できません。 -> - ログ、監査情報、非同期タスク精算でノードを特定しやすくするため、安定した `NODE_NAME` を設定することを推奨します。 -> - 本番環境では外部データベース、外部 Redis、HTTPS リバースプロキシ、信頼できるバックアップ戦略を使用してください。 +> SQLite はローカル評価、開発、小規模テスト向けです。本番環境では、ベンダーのセキュリティサポート期間内にある MySQL（8.4 LTS 推奨）または PostgreSQL（14+ 推奨）を使用し、Redis、HTTPS、バックアップ、復旧手順を構成してください。互換性の下限は MySQL ≥ 5.7.8、PostgreSQL ≥ 9.6 ですが、これらのバージョンを本番で使用することは推奨しません。 ---- +## ✨ 現在の機能 -## 🗺️ ロードマップ +現在のシステムでは、次の機能を提供しています： -以下は方向性の計画であり、保守ペース、実運用シーン、コミュニティ要望に応じて調整されます。時期を保証するものではありません。 +| 機能 | 主な用途 | +|---|---| +| 統一モデル入口 | OpenAI Compatible、Responses、Claude Messages、Gemini、Realtime、マルチモーダルタスク API を接続 | +| マルチプロバイダールーティング | チャネル、重み、優先度、グループ、モデルマッピング、リトライ、プロバイダー間切り替えを管理 | +| アイデンティティ／アクセス制御 | ユーザー、トークン、モデル範囲、グループ、クォータ、有効期限、レート制限、管理者権限を管理 | +| コスト／課金 | 倍率、固定価格、式ベース課金、非同期タスク rate-card、事前課金、精算、失敗時返金 | +| ログ／監査 | ユーザー、トークン、モデル、チャネル、グループ、ノード別に利用、エラー、リトライ、管理操作を確認 | +| インテリジェント運用センター | アクティブアラート、チャネル／モデル性能、システム情報、課金精算照合 Evidence を一元確認 | +| プライベートデプロイ | SQLite、MySQL、PostgreSQL、Redis、複数ノード、独立ログデータベース | +| 上流拡張性 | プロトコルアダプター、パス、パラメーター／Header の上書き、モデル発見、タスク状態マッピング | -- **モデルガバナンスの深化**：モデルカタログ、価格、権限、マッピング、能力タグ、プロバイダー変更への対応を強化します。 -- **AgentOps の深化**：Agent、ツール呼び出し、ワークフロー、MCP-style ツール / サービス接続における呼び出しチェーン、コスト帰属、障害診断、ガバナンスを改善します。 -- **マルチモーダルタスクガバナンス**：画像、動画、音声、リアルタイム対話タスクの課金、制限、状態追跡、結果プロキシを強化します。 -- **プロトコル変換の強化**：OpenAI Compatible、Responses、Claude Messages、Gemini などの変換を継続的に改善します。 -- **中国国内モデル・平台の継続適応**：国内モデル、クラウド平台、価格ルール、API プロトコルの変化を追跡し、再利用可能なチャネル、価格、タスクプロトコル設定を蓄積します。 -- **プロバイダー適応のテンプレート化**：パス上書き、タスクプロトコル、状態マッピング、エラー解析、結果解析をより設定・再利用しやすくします。 -- **ガバナンス監査と運用最適化**：リクエストチェーン、コスト追跡、エラー分析、管理者監査、ログ保持、運用レポートを改善します。 -- **組織レベル運用能力**：マルチテナント、グループ、請求、権限、リスク制御、プライベートデプロイ体験を強化します。 +### 利用シーン -要望、問題、改善提案は [GitHub Issues](https://github.com/MAX-API-Next/MAX-API/issues) で歓迎します。 +- **チーム／組織内モデルゲートウェイ**：ユーザー、トークン、モデル、プロバイダー、権限、費用を一元管理。 +- **AI アプリケーション／Agent の実行基盤**：アプリケーション、Agent、ワークフローにモデルアクセス制御、コスト帰属、障害診断を提供。 +- **マルチプロバイダーの冗長化と移行**：モデルマッピング、重み付きルーティング、リトライ、段階的切り替えで単一上流への依存を軽減。 +- **マルチモーダルタスクガバナンス**：画像、音声、動画、埋め込み、リランキング、リアルタイム会話 API を統一管理。 +- **プライベート／コンプライアンス運用**：秘密情報、データ、ログ、監査、価格、デプロイ環境を自主管理。 ---- +## 🩺 インテリジェント運用センター -## ❓ FAQ +**インテリジェント運用センターは MAX API 2.0 の主要アップデートであり、統一モデルゲートウェイから AGI ネイティブなガバナンス／運用基盤へ進む重要な一歩です。** -
-MAX API はモデルサービスや API Key を提供しますか？ +本番観測、リソースアラート、モデル／チャネル性能、システム情報、課金精算照合を一つの管理者入口に集約します。現在の機能は「問題を可視化する、証拠を残す、管理者に通知する、制御されたレビューを行う」ことに重点を置いています。チャネル、ルーティング、残高、ホストを自動変更する自律 Agent ではありません。 -いいえ。MAX API はモデルと Agent ワークロードのゲートウェイガバナンスレイヤーです。上流モデルアカウント、API Key、基盤モデル学習、モデルサービス自体は提供しません。利用者は合法的に認可された上流サービスを自ら取得する必要があります。 +| モジュール | 現在提供する内容 | +|---|---| +| アクティブアラート | 現在のノードで CPU、メモリ、ディスクが閾値を継続超過した場合の重複排除アラートと復旧通知。管理者の既存 Email、Webhook、Bark、Gotify 設定を再利用 | +| チャネル性能 | リクエスト／エラー、消費クォータ、推定成功率、ログレイテンシ、リトライ、プローブレイテンシ、最終観測時刻。詳細では過去 24 時間のモデル／グループ性能を表示 | +| モデル性能 | チャネル数、リクエスト／エラー、消費クォータ、推定成功率、ログレイテンシ、スループット、リトライを集約。詳細ではグループ性能、レイテンシ、可用率の傾向を表示 | +| 課金精算照合 | `pending` / `manual` の正方向最終精算、未精算資金、リトライ、エラー Evidence を表示。ルート管理者はデフォルトのユーザーブロック方針を設定でき、管理者は `id + revision` 単位でアトミックに一括レビューしてアラートを閉じられる | +| システム情報 | ノード、実行インスタンス、システムタスクなどを表示。このモジュールは引き続きスーパー管理者権限が必要 | -
+アクティブアラート画面は 5 秒ごとに現在の状態を読み取りますが、新たな検出や修復は実行しません。チャネル／モデル一覧はデフォルトで直近 1 時間を検索し、`1–168` 時間のカスタム範囲を指定できます。大規模ログデータベースを自動で繰り返し集計せず、「フィルターを適用」または「更新」を押したときだけ検索し、詳細データは必要時に読み込みます。 -
-MAX API と Agent フレームワークの関係は？ +課金精算照合は、財務復旧状態と運用アラート状態を厳密に分離します。「レビューして閉じる」は管理者レビューを記録し現在のアラートを閉じるだけで、精算を `applied` に変更せず、残高、適用済み差額、effect 状態も変更しません。一括レビューは現在の財務 revision に拘束されます。更新後に記録が変わった場合、古い選択は自動的に無効となり、古い証拠に基づく操作を防ぎます。 -MAX API は Dify、LangChain、MCP Server、ワークフローエンジン、業務 Agent アプリケーションを置き換えません。それらのアプリケーションと上流モデルサービスの間に位置し、モデル接続、トークン分離、コスト計算、ルーティング冗長化、ログ観測、管理者監査を担当します。 - -
- -
-なぜ AI モデルガバナンスを強調するのですか？ +> [!NOTE] +> 現在の本番性能表示は主に既存の Consume/Error ログと `perf_metrics` を集約します。推定成功率は完全な Relay Attempt 成功率ではなく、スループットと傾向は性能バケット単位の近似値です。ログ無効、履歴不足、収集停止、対象期間にサンプルなし、検索失敗の場合、対応するデータ品質状態を表示します。 +> +> アクティブアラートは性能監視とリソース閾値設定に依存します。閾値 `0` はそのリソースアラートを無効化し、発火には連続する 2 つの有効サンプルが必要です。状態と通知キューは現在のプロセスメモリだけに保存されるため、再起動後には残らず、複数ノード間で自動的に Incident へ統合されません。チャネル、モデル、システムの観測は読み取り専用です。精算レビューはレビューのメタデータとユーザーブロック方針だけを更新し、資金精算を実行しません。インテリジェント運用センターは、テスト、無効化、重み変更、チャネル切り替え、ホスト修復を自動実行しません。 -実際の組織では、モデルは単なる API 名ではありません。プロバイダー、価格、コンテキスト長、プロトコル形式、権限範囲、安定性、監査境界が関係します。MAX API の価値は、これらの分散した変数を統一的に設定、観測、計算できることです。 +この段階ではまず「問題を見る、管理者へ通知する、証拠を提示する、制御されたレビューを行う」ループを完成させ、統一 Evidence、診断 Agent、Evaluator、制御された自動化の基盤を作ります。 -
+## 🔌 モデル、インターフェース、拡張性 -
-どのデータベースに対応していますか？ +> 実際に利用できる機能は、上流の利用権限、チャネル設定、モデルマッピング、プロバイダー対応状況に依存します。MAX API はこれらの機能をガバナンスしますが、モデルサービス自体は提供しません。 -SQLite、MySQL ≥ 5.7.8、PostgreSQL ≥ 9.6 に対応しています。ローカル評価には SQLite、本番環境には MySQL または PostgreSQL とバックアップを推奨します。 +| カテゴリ | インターフェース／機能 | +|---|---| +| 一般モデル API | Chat Completions、Responses、Embeddings、Rerank、Images、Audio、Video | +| ネイティブ／リアルタイムプロトコル | Claude Messages、Google Gemini、OpenAI Realtime など | +| 推論／ツール呼び出し | Reasoning Effort、関数ツール、Tool Call ID、ツール名、マルチターンのツール応答関連付け。上流能力に応じてプロトコル変換 | +| 非同期タスク | タスク送信、ポーリング、状態マッピング、結果プロキシ、パラメーター化課金 | +| カスタム上流 | Base URL、パス、パラメーター、Header、状態フィールド、結果フィールドのマッピング | -
+OpenAI、Claude、Gemini、Azure、AWS Bedrock、Vertex AI、Ollama、および複数の中国系モデルプラットフォームをカバーします。Codex、Dify、RAGFlow、マルチモーダルタスクサービスのガバナンスにも利用できます。正確な対応範囲は現在のバージョンとチャネル種別に依存します。 -
-New API / One API から移行できますか？ +### システムフローと技術スタック -本プロジェクトは New API と元の One API の主要データ構造と互換性があります。既存データは通常再利用できますが、移行前にデータベースをバックアップし、テスト環境でチャネル、倍率、ユーザー、トークン、ログを検証してください。 +![MAX API システムアーキテクチャ](./docs/images/MAX-API架构图.png) -
+```text +Application / SDK / Agent + → 統一インターフェースと認証 + → モデル権限、レート制限、予算、セキュリティチェック + → チャネル選択、マッピング、失敗時リトライ + → 上流プロトコル適応 + → 回復可能な精算、Evidence、ログ、監査 + → インテリジェント運用センターと管理者ガバナンス +``` -
-複数ノードデプロイで注意することは？ +バックエンドは Go、Gin、GORM、フロントエンドは React 19、TypeScript、Base UI、Tailwind CSS を使用します。データ層は SQLite、MySQL、PostgreSQL に対応し、必要に応じて Redis と独立ログデータベースを利用できます。プロバイダープロトコルアダプターは専用の Relay/Channel 層にあり、課金と精算は統一サービス境界に集約され、SmartOps は読み取り専用の観測と制限されたガバナンス入口を提供します。 -全ノードで同じ `SESSION_SECRET` を使用してください。共有 Redis を使用する場合は同じ `CRYPTO_SECRET` も必要です。異なる場合、ログイン状態不一致、キャッシュ復号失敗、タスク状態異常が起きる可能性があります。 +## 🛡️ ガバナンスと運用 -
+本番環境では、次の順序で設定することを推奨します： -
-画像生成、ストリーミングレスポンス、大きなレスポンスが切れる場合は？ +1. ログイン、安全制限、ユーザー登録方針を設定する。 +2. 正当な利用権限を持つ上流チャネルを追加し、モデル、機能、プロトコル設定を確認する。 +3. チーム、業務、環境ごとにグループ、トークン、モデル範囲、クォータ、価格を設定する。 +4. アプリケーション、Agent、環境ごとに別のトークンを使用し、認証情報の共有と不明確なコスト帰属を避ける。 +5. リトライ、ログ、アラートを設定し、ダッシュボードとインテリジェント運用センターで継続的に観測する。 -`STREAM_SCANNER_MAX_BUFFER_MB` を大きくしてください。4K 画像、base64 画像、長いストリーミングレスポンスではより大きなバッファが必要になる場合があります。 +チャネル能力の検証、式ベース課金、汎用タスクプロトコル、管理者監査、性能設定については、[詳細ドキュメント](https://docs.max-api.ai)を参照してください。 -
+## 🧭 進化ロードマップ -
-大きなリクエストで 413 が返る場合は？ +MAX API は今後も **AI Models and Agents governance** を中核とします。統一ゲートウェイ、インテリジェント運用、回復可能な精算を起点に、AGI アプリケーション向けの Evidence、評価、Policy、制御された実行能力を段階的に構築します。長期的な方向性は、境界のない Agent に本番を任せることではなく、検証可能、承認可能、停止可能、ロールバック可能なエンジニアリングループを作ることです。 -`MAX_REQUEST_BODY_MB` を調整してください。この制限は解凍後のリクエストボディサイズで計算され、巨大リクエストや zip bomb によるメモリ増加を防ぎます。 +| 段階 | 状態 | 重点 | +|---|---|---| +| 統一ゲートウェイとインテリジェント運用 | **提供中** | 接続、認証、ルーティング、課金、ログ、リソースアラート、チャネル／モデル性能、システム情報、課金精算照合 | +| Evidence 事実レイヤー | **短期開発** | モデルリクエスト、システムログ、メトリクス、Task、ルーティング、Policy、精算、監査イベントを統一し、匿名化・権限制限された読み取り専用 Agent API を提供 | +| オープン評価とガバナンステンプレート | **計画中** | コミュニティとモデル／プロトコル互換性テスト、匿名化障害事例、評価セット、Runbook、Detector、業界向けテンプレートを構築 | +| 制御された自律運用 | **長期ビジョン** | Policy、Budget、Approval、Shadow、Canary、Rollback の制約下で低リスクの自動操作を評価 | +| 制御された能力進化 | **長期ビジョン** | 分離された Coding Workspace で改善候補を生成、テスト、レビューし、本番を直接変更しない | +| AGI エンジニアリングループ | **長期方針** | Evidence、評価、ガバナンス方針、人による承認、ロールバック可能な実行を検証可能なループに接続 | -
+MAX API は基盤モデルではなく、現時点で AGI や自律運用を実現済みと主張しません。長期機能は Evidence、権限、予算、承認、ロールバックの境界が整った後にのみ段階的に検証します。 -
-ユーザーは管理者ログ監査の入力・出力内容を見られますか？ +## 🚢 Preview デプロイ -通常ユーザー向けログ API は管理者専用フィールドを除外するため、ユーザーがセルフサービスの利用ログで管理者監査内容を見ることはできません。ただし、データベース管理者、システム管理者、管理者ログ API 権限を持つ人は関連データにアクセスできる可能性があるため、権限を厳格に管理してください。 +以下の手順は Preview 版のテストと段階的検証向けです。本番環境では正式版を使用し、同じ検証とロールバック手順を維持してください。 -
+Docker Compose を推奨します： -
-Docker ビルドで `catalog:` 依存関係を解決できないのはなぜですか？ - -フロントエンドは Bun workspace を使用しており、`catalog:` 依存関係は `web/package.json` に定義されています。ビルド時に workspace ルートの `package.json` を `web/default/package.json` で上書きせず、`web/bun.lock` を保持してください。 - -
- ---- - -## 🔗 関連プロジェクト - -| プロジェクト | 説明 | -|------|------| -| [One API](https://github.com/songquanpeng/one-api) | MIT License | -| [New API](https://github.com/QuantumNous/new-api) | AGPLv3 License | -| [Midjourney-Proxy](https://github.com/novicezk/midjourney-proxy) | Apache-2.0 License | -| [Suno API](https://github.com/Suno-API/Suno-API) | MIT License | - -### 関連ツール - -| プロジェクト | 説明 | -|------|------| -| [max-api-key-tool](https://github.com/MAX-API-Next/MAX-API-key-tool) | Key クォータ確認ツール | -| [max-api-horizon](https://github.com/MAX-API-Next/MAX-API-horizon) | MAX API 高性能最適化版 | +```bash +MAX_API_VERSION=v2.0.0-smartops.pre1 +MAX_API_COMMIT=b7096156549edc930ca244891afb1ba5632dbe8f +git clone --branch "$MAX_API_VERSION" --depth 1 https://github.com/MAX-API-Next/MAX-API.git +cd MAX-API ---- +actual_commit="$(git rev-parse HEAD)" +if [ "$actual_commit" != "$MAX_API_COMMIT" ]; then + echo "Unexpected commit: $actual_commit" >&2 + exit 1 +fi -## 📚 ドキュメントとサポート - -| リソース | リンク | -|------|------| -| 公式ドキュメント | [MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) | -| 問題報告 | [GitHub Issues](https://github.com/MAX-API-Next/MAX-API/issues) | -| 最新リリース | [Releases](https://github.com/MAX-API-Next/MAX-API/releases) | -| DeepWiki | [Ask DeepWiki](https://deepwiki.com/MAX-API-Next/MAX-API) | - -### 二次開発とコミュニティへの謝辞 - -本プロジェクトをベースに二次開発し、ご自身で利用する場合は、プロジェクトのホームページ、フッター、または「About」ページなどの目立つ場所に、次のいずれかの方法でプロジェクトの出典またはコミュニティへの謝辞を表示できます： - -- プロジェクトへのリンク：[MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) -- コミュニティへの謝辞：[MAX-API-Next](https://github.com/MAX-API-Next) - -フロントエンドへの埋め込み例（React / Tailwind CSS、必要に応じていずれか一方のみ残してください）： - -```tsx -

- {' '} - - MAX-API-Next/MAX-API - {' '} - を基に二次開発 ·{' '} - - MAX-API-Next コミュニティ - {' '} - に感謝 -

+# docker-compose.yml のデータベース／Redis パスワードと秘密情報を変更 +docker compose up -d ``` -上記いずれかの表示要件を満たし、リンクを明確に表示し続けることで、申請や承認を別途行うことなく、本プロジェクトの一時的な商用ライセンスを自動的に取得できます。このライセンスは永久ライセンスではなく、表示要件を継続して満たしている期間に限り有効です。有効期間および今後の変更は、本 README または公式コミュニティで公開される最新のお知らせに従います。 +### デプロイチェック -本プロジェクトは [One API](https://github.com/songquanpeng/one-api) および [New API](https://github.com/QuantumNous/new-api) をベースに開発されています。現段階の MAX API は、これらを基盤として AI API ゲートウェイおよびガバナンス機能の強化、機能拡張、バグ修正を継続しています。商用利用にあたっては、各上流プロジェクトが現在公開している `LICENSE` ファイルに従い、One API の MIT ライセンスおよび New API の AGPLv3 ライセンスも遵守する必要があります。本プロジェクトが提供する一時的な商用ライセンスは、上流プロジェクトのオープンソースライセンス上の義務を置き換えたり免除したりするものではありません。 +| コンポーネント | 推奨 | +|---|---| +| データベース | ベンダーのセキュリティサポート期間内にある MySQL（8.4 LTS 推奨）または PostgreSQL（14+ 推奨）を使用し、バックアップと復旧を構成 | +| キャッシュ | 1 ノードではメモリキャッシュを利用可能。複数ノードでは Redis を推奨 | +| エントリーポイント | HTTPS リバースプロキシ、リクエストサイズ制限、信頼済みネットワーク方針を設定 | +| 秘密情報 | ランダムな `SESSION_SECRET` を明示設定。`CRYPTO_SECRET` は任意の上書き値で、未設定時は `SESSION_SECRET` を使用し、設定する場合は Redis／複数ノードで同じ値を共有 | +| ノード | 各ノードに安定した一意の `NODE_NAME` を設定 | +| ログ | コンプライアンスと運用要件に合わせて `LOG_SQL_DSN`、クリーンアップ、保持方針を設定 | -表示要件を満たさなくなった場合、または一時的なライセンスが期限切れ、告知により変更もしくは終了した場合は、AGPLv3 に従うか、別途書面による許諾を取得する必要があります。長期商用ライセンスについては、maxapi@max-api.ai までお問い合わせください。 +複数ノードでは `SESSION_SECRET` を共有し、各ノードに異なる `NODE_NAME` を設定する必要があります。`CRYPTO_SECRET` は任意の上書き値で、未設定時は `SESSION_SECRET` を使用します。明示的に設定する場合は、すべてのノードで同じ値を使用してください。独立ログデータベースには `LOG_SQL_DSN` を使用し、エラー性能統計が必要な場合は `ERROR_LOG_ENABLED` を有効にしてください。すべての環境変数とソースビルド手順は[詳細ドキュメント](https://docs.max-api.ai)を参照してください。 -Issue、ドキュメント改善、プロバイダー適応経験、デプロイ方案、コード貢献を歓迎します。 +## 🤝 プロジェクトの由来、謝辞、二次開発 ---- +MAX API は、[One API](https://github.com/songquanpeng/one-api) と [New API](https://github.com/QuantumNous/new-api) のオープンソース成果を基に開発を継続しています。上流プロジェクトと貢献者、プロトコル適応、テスト、ドキュメント、翻訳、Issue 報告に参加するすべてのコミュニティメンバーに感謝します。 -## 📜 ライセンス +[NOTICE](./NOTICE) および AGPLv3 第 7 条に従い、ユーザーインターフェースを持つ変更版は、About、法的表示、フッター、または帰属表示の見やすい場所に、次のすべてを保持する必要があります： -本プロジェクトは [GNU Affero General Public License v3.0 (AGPLv3)](./LICENSE) で提供されます。 +- MAX API の元プロジェクトへのリンク：[MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) +- MAX API NOTICE の正確な帰属表示：`Frontend design and development by MAX API contributors.` +- 上流 New API プロジェクトへのリンク：[QuantumNous/new-api](https://github.com/QuantumNous/new-api) +- New API NOTICE の正確な帰属表示：`Frontend design and development by New API contributors.` +- 変更したことを示す明確な表示と、関連する変更日 -標準の AGPLv3 ライセンスに加え、上記「二次開発とコミュニティへの謝辞」の条件を満たす自己利用の二次開発プロジェクトには、そこで説明されている非永久の一時的な商用ライセンスが自動的に付与されます。この一時的なライセンスが対象とするのは、MAX API プロジェクト運営者がライセンスする権利を有する追加・変更部分のみであり、One API や New API などの上流プロジェクトのライセンスを含む、または代替するものではありません。 +[MAX-API-Next コミュニティ](https://github.com/MAX-API-Next)への謝辞は任意で追加できますが、必須のプロジェクトリンク、正確な帰属表示、変更表示の代わりにはなりません。 -本プロジェクトを変更し、ネットワーク経由でユーザーにサービスとして提供する場合は、AGPLv3 のソース提供義務などを理解し遵守してください。商用協力、機関協力、その他ライセンスに関する問い合わせは maxapi@max-api.ai までご連絡ください。 +これらの表示要件と NOTICE の要件を継続して満たすことで、別途申請や承認を待つことなく、非永続的な一時商用ライセンスが自動的に付与されます。この追加許諾は MAX API プロジェクト側がライセンスする権利を持つ部分だけを対象とし、AGPLv3、One API、New API、その他の上流プロジェクトのライセンス義務を免除しません。最新条件は正式 README と公式コミュニティの告知に従います。 ---- - -## 🌟 Star History +## 📜 ライセンス -
+本プロジェクトは [GNU Affero General Public License v3.0（AGPLv3）](./LICENSE) の下で提供されます。 -[![Star History Chart](https://api.star-history.com/svg?repos=MAX-API-Next/MAX-API&type=Date)](https://star-history.com/#MAX-API-Next/MAX-API&Date) +一時商用ライセンスが対象とするのは、MAX API プロジェクト側がライセンスする権利を持つ追加・変更部分のみです。One API、New API、その他の上流プロジェクトのライセンス義務を含めたり、置き換えたり、免除したりするものではありません。商用利用では、One API の MIT ライセンス、New API の AGPLv3 ライセンス、および各上流プロジェクトの最新条件にも従ってください。 -
+本プロジェクトを変更し、ネットワーク経由でユーザーへ提供する場合は、AGPLv3 のソースコード提供義務を理解し、遵守してください。長期商用ライセンス、機関との協力、その他のライセンスに関する問い合わせは maxapi@max-api.ai までご連絡ください。 --- @@ -705,9 +354,9 @@ Issue、ドキュメント改善、プロバイダー適応経験、デプロイ ### 💖 MAX API をご利用いただきありがとうございます -このプロジェクトが役に立った場合は、ぜひ ⭐ Star をお願いします。 +このプロジェクトが役に立った場合は、⭐ Star、Releases のフォロー、再現可能な Issue の報告、MAX-API-Next コミュニティへの参加をお願いします。 -**[公式ドキュメント](https://github.com/MAX-API-Next/MAX-API)** • **[Issues](https://github.com/MAX-API-Next/MAX-API/issues)** • **[Releases](https://github.com/MAX-API-Next/MAX-API/releases)** +**[プロジェクトリポジトリ](https://github.com/MAX-API-Next/MAX-API)** • **[貢献する](https://github.com/MAX-API-Next/MAX-API/issues)** • **[最新リリース](https://github.com/MAX-API-Next/MAX-API/releases)** • **[MAX-API-Next コミュニティ](https://github.com/MAX-API-Next)** Built with ❤️ by MAX-API-Next diff --git a/README.md b/README.md index 250aedbf..4bf56c80 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,14 @@ -
+# MAX API -![max-api](/web/default/public/logo.png) +
-# MAX API +![MAX API](./web/default/public/logo.png) + +**面向 AGI 应用时代的 AI Models 与 Agents 治理、智能运维和开放协作基础设施** + +**MAX API 2.0：开启智能运维时代 · 从统一模型网关走向 AGI 原生治理与运营** -🍥 **AI 模型治理、AgentOps 与 AGI 应用服务基础设施** +[查看 MAX API 2.0 Preview 发布说明](https://github.com/MAX-API-Next/MAX-API/releases/tag/v2.0.0-smartops.pre1)

简体中文 | @@ -30,738 +34,321 @@

- 项目定位 • - 发布渠道 • - 治理框架 • - 适用场景 • + ⭐ Star 项目 • + 💬 加入社群 • + 📚 查看文档 • + 🚀 获取版本 +

+ +

+ 加入社区 • 快速开始 • - 核心能力 • - 治理配置 • - 架构概览 • - 模型与接口 • - 部署 • - FAQ • - 许可证 + 为什么需要 • + AGI 技术方向 • + 当前能力 • + 智能运维 • + Preview 部署

--- -## 📝 项目说明 - -MAX API 是由来自科研机构和高校的 AGI 爱好者组织发起、维护和长期运营的 AI 模型治理、AgentOps 与应用服务基础设施项目，面向开发者、研究者、团队和组织提供稳定、可复用的服务层能力。项目关注 AI 应用落地后的持续运营问题：模型越来越多、供应商接口频繁变化、Agent 调用链路变长、成本和审计压力增加。MAX API 在应用、Agent、用户、组织和上游模型服务之间提供统一的接入、鉴权、路由、计费、观测和治理层，让 AI 应用更稳定、更可控地运行。 - -换句话说，MAX API 不只是请求转发器，而是面向 AI-ready 应用和 Agent 工作负载的可运营网关：在统一模型协议与供应商差异的同时，把突发流量、长流式响应、大请求体、多节点缓存、成本审计和性能观测放进同一套治理边界。 - -持续投入方向： - -- **AI 模型治理**：持续跟踪 OpenAI、Azure OpenAI、AWS Bedrock、Vertex AI、Ollama，以及 DeepSeek、通义千问 / 阿里云百炼、智谱 GLM、Kimi、豆包 / 火山引擎、腾讯混元、百度文心 / 千帆、讯飞星火、MiniMax、零一万物、硅基流动等模型与平台的模型更新、接口变化、参数差异、价格规则和任务协议；同时关注 Dify、RAGFlow、Kling、Seedance 等应用和多模态生态的接入形态，通过渠道、模型映射、协议转换、路径覆盖和可配置任务协议，把分散模型能力纳入统一治理。 -- **AI Agent 治理 / AgentOps**：围绕 Agent、工作流和工具调用场景，持续完善令牌治理、模型访问控制、调用追踪、成本归因、异常定位和日志审计，并为后续 MCP 风格工具 / 服务接入预留统一治理边界，帮助 Agent 应用在真实业务中更可观测、更可运营。 -- **渠道配置治理**：在渠道新建和编辑界面提供渠道能力矩阵与配置校验，直观展示 `chat/completions`、`responses`、`embeddings`、`rerank`、`video tasks`、模型发现等能力，并提前提示 Base URL、JSON 配置、Vertex AI 区域、Codex 凭证、视频任务占位符等常见配置风险。 -- **运营优化与成本治理**：持续优化渠道路由、失败重试、限流、预扣费、失败退款、日志观测、成本统计和运维分析；文本与多模态 token 场景可使用表达式计费和统一 JSON 配置，视频等异步任务场景可使用参数化 rate-card，让模型成本和 Agent 调用成本更直观、可核算、可批量维护。 - -> [!IMPORTANT] -> - 面向公众提供生成式人工智能服务时，使用者应遵守[《生成式人工智能服务管理暂行办法》](http://www.cac.gov.cn/2023-07/13/c_1690898327029107.htm)等监管要求，并自行完成所在司法辖区要求的备案、许可、内容安全、实名、日志留存、税务、支付和上游授权等合规义务。 -> - 日志审计、内容留存等敏感能力应仅在具备合法依据、明确告知、权限隔离和数据安全措施的场景下启用。 -> - MAX API 提供模型与 Agent 工作负载的网关治理层，不提供上游模型账号、密钥、基础模型训练能力，也不替代 Dify、LangChain、MCP Server 等 Agent 编排或应用开发框架。 - ---- - -## 🚦 发布渠道 - -MAX API 当前版本发布分为正式版和 Preview 预览版。Preview 预览版用于提前开放新能力和修复，便于社区与部署者在真实环境中验证兼容性、稳定性和安全性；正式版会在对应 Preview 预览版稳定运行 1 周后发布，以降低生产环境升级风险，保障系统安全性和可靠性。 - -生产环境建议优先使用正式版；需要提前验证新功能、修复或兼容性变化时，可在测试环境或灰度环境使用 Preview 预览版，并在升级前做好数据库备份和回滚预案。 - -### 💬 社区访问 - -- 🌐 GitHub 地址：[https://github.com/MAX-API-Next](https://github.com/MAX-API-Next) -- 👥 社群交流：QQ(950126533) | 微信群(搜索MAX-API) - ---- - -## 🎯 项目定位 +MAX API 位于应用、Agent 与上游模型服务之间，是统一的模型网关、治理控制平面和运营入口。MAX-API-Next 社区围绕 AGI 工程化持续建设本项目，并面向开发者、研究者、企业工程团队、高校技术爱好者和开源贡献者开放协作。我们的目标是建设 AGI 应用真正需要的模型接入、权限、成本、Evidence、智能运维和安全控制基础。 -image - -在 AGI 应用时代，MAX API 聚焦于开放的 AI 模型治理和 AI Agent 治理基础设施，建设让开发者和组织能够稳定运行 AI 应用与 Agent 工作负载的服务、治理和运营层： - -- **模型治理平面**：统一管理模型入口、渠道、供应商、协议格式、模型映射、价格规则、任务协议和多模态接口。 -- **AgentOps 控制平面**：不替代 Agent 编排框架，而是在网关层为 Agent 工作负载提供令牌治理、模型访问控制、调用日志、成本追踪、异常定位和运营分析。 -- **渠道配置平面**：通过能力矩阵、表单校验、模型发现和协议模板，降低新增上游渠道、迁移供应商和维护非标准接口时的误配置风险。 -- **协议与供应商适配层**：持续跟踪海外官方接口、国产模型平台接口（DeepSeek、通义、智谱、火山引擎、百度千帆等）以及各类 OpenAI 兼容 / 非标准接口的变化，并规范化为稳定的应用侧接口。 -- **成本、额度与可靠性治理**：支持渠道路由、加权分发、失败重试、限流、预扣费、失败退款，以及表达式计费、固定价格、任务 rate-card、倍率计费和用量统计。 -- **性能与可扩展性治理**：通过 Redis / 内存缓存、模型请求限流、流式超时与大响应缓冲、请求体上限、磁盘缓存、Pyroscope 性能采样和优雅关闭，支撑单机到多节点部署的稳定运行。 -- **组织级运营与审计层**：为团队、研究机构、企业和社区服务提供用户管理、分组管理、私有化部署、数据留存、审计和持续运营优化能力。 -- **可复用治理模板**：沉淀渠道模板、任务协议模板、价格配置、部署实践和运维经验，降低新模型、新供应商和新 Agent 场景的接入成本。 - ---- +我们将在 AGI 领域：**持续交付先进而可验证的技术、将真实生产问题沉淀为开放工程能力、建立能够共同研究和贡献的社区。** -## 🧠 治理框架 +## 🌐 加入 MAX-API-Next 社区 -MAX API 的设计把 AI 模型和 AI Agent 的运行过程纳入可配置、可观测、可核算、可审计的治理框架。 - -| 治理对象 | MAX API 提供的能力 | 目标 | -|----------|-------------------|------| -| 模型资产 | 模型列表、模型映射、模型分组、模型限制、价格规则和多模态接口管理 | 让组织知道“有哪些模型、谁能用、怎么计费、如何切换” | -| 上游渠道 | 供应商渠道、权重、分组、状态、密钥、Base URL、路径覆盖、能力矩阵、配置校验、模型发现和失败重试 | 降低单一供应商不可用、涨价、限流、误配置或接口变化带来的风险 | -| 协议格式 | OpenAI Compatible、Responses、Claude Messages、Gemini、Realtime、通用视频任务协议等协议入口和转换 | 让应用侧尽量面对稳定接口，而不是直接承担各家协议差异 | -| Agent 令牌 | API Key、令牌分组、模型范围、额度限制、过期时间和访问控制 | 为 Agent、工作流和工具调用分配独立、可回收、可限额的访问凭据 | -| 用量与成本 | 请求日志、用量统计、表达式计费、分阶段计费 JSON、任务 rate-card、预扣费和失败退款 | 把模型调用成本拆到用户、分组、令牌、模型、渠道和节点维度 | -| 异步任务 | 视频等任务提交、轮询、状态映射、结果代理和任务计费 | 统一治理长耗时、多状态、多上游格式的多模态任务 | -| 审计与安全 | 管理员侧日志审计、错误日志、请求限制、流式超时、登录与权限控制 | 在私有化部署和合规场景中提供可控的审计边界，敏感内容审计集中放在安全与限制中管理 | -| 组织运营 | 用户、分组、余额、支付、系统设置、数据看板和运维配置 | 支撑团队、研究机构、企业或社区服务的持续运营 | - ---- - -## 🧩 适用场景 - -- **组织内部 AI 模型治理平台**：统一管理用户、令牌、模型、渠道、分组、权限、价格和账单，避免每个团队重复接入和维护上游服务。 -- **Agent 应用运行与治理底座**：为 Agent、工作流和工具调用应用提供稳定的模型网关、令牌隔离、成本控制、调用观测、异常定位和审计基础。 -- **国产模型与多供应商适配中心**：持续跟踪国内外模型平台接口和价格变化，通过渠道配置、模型映射、路径覆盖和协议模板降低适配成本。 -- **多模态任务治理平台**：统一接入文本、图像、视频、音频、嵌入、重排序、实时对话等接口，并对异步任务做状态、结果代理和计费治理。 -- **模型成本与 Agent 成本核算平台**：围绕用户、令牌、模型、渠道和分组进行额度分配、费用核算、账单统计和成本分析。 -- **私有化与合规运营环境**：适合需要自主管理密钥、数据、权限、日志、审计和计费策略的团队或机构。 - ---- - -## 🚀 快速开始 +MAX API 不只是一个代码仓库，也是一项面向 AI Models、Agents、AgentOps 与 AGI 工程化的长期开放协作。无论你正在部署模型网关、开发 Agent、适配新模型、研究评测与治理，还是愿意改进文档和国际化，都欢迎加入社群交流并参与共建。 -默认使用 SQLite，本地体验无需额外数据库。 +**加入社群，你可以更快获取版本动态、模型与协议变化、部署经验、问题排查线索和社区共建机会。** -> [!WARNING] -> SQLite 仅适合本地体验、开发和小规模测试。正式/生产环境不建议使用 SQLite：在并发请求、多实例部署、大量日志与用量数据、数据库迁移、备份恢复或长事务场景下，可能出现锁等待、写入阻塞、迁移耗时或失败，以及可用性和数据维护问题。正式环境请使用 MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6，并配置可靠的备份与恢复方案。 - -```bash -# 1. 拉取镜像 -docker pull cscitechtop/max-api:latest - -# 2. 启动服务，数据持久化到当前目录 ./data -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest - -# 3. 访问控制台 -# 浏览器打开 http://localhost:3000 -``` - -生产部署建议使用 Docker Compose，并显式配置数据库、Redis、会话密钥、加密密钥和日志目录。 - -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API - -# 按需修改 docker-compose.yml 中的数据库、Redis 密码和环境变量 -docker compose up -d -``` - -> [!WARNING] -> 将本项目作为面向公众的生成式 AI 服务或 API 服务运营时，应先完成上游授权、备案、内容安全、实名、日志留存、税务、支付和用户协议等合规事项。 - ---- - -## ✨ 核心能力 - -### AI 模型治理 - -| 能力 | 说明 | -|------|------| -| 统一模型入口 | 支持 OpenAI 兼容接口、Responses、Claude Messages、Gemini、Realtime 等多种协议入口，应用侧可通过统一网关访问模型 | -| 多供应商模型池 | 海外可接入 OpenAI、Azure、Claude、Gemini、AWS Bedrock、Vertex AI、Ollama；国产方向持续跟踪并内置 DeepSeek、通义千问、智谱 GLM、Kimi、豆包、腾讯混元、文心、讯飞星火、MiniMax、零一万物、硅基流动等渠道适配 | -| 上游生态适配 | 支持 Codex、Dify、RAGFlow、Kling、Seedance 等应用、Agent 和多模态平台相关接口的接入治理，便于把模型调用、工作流调用和异步任务纳入统一网关 | -| 模型映射与访问范围 | 支持按渠道配置模型列表、模型映射、用户分组、令牌分组和模型限制，让不同团队、应用或 Agent 使用不同模型集合 | -| 渠道能力矩阵 | 渠道编辑界面展示 `chat/completions`、`responses`、`Claude Messages`、`Gemini native`、`embeddings`、`images`、`audio`、`rerank`、`video tasks`、`model discovery` 等能力状态，减少管理员对渠道能力的猜测 | -| 渠道配置校验 | 在保存前检查 API Key、模型列表、Base URL、额外配置、JSON 对象、Vertex AI 区域、Codex 凭证、模型发现能力和视频任务路径占位符等常见问题 | -| 多模态模型治理 | 支持聊天、图像、视频、音频、嵌入、重排序、实时对话等场景，并对视频等异步任务提供提交、轮询、状态映射和结果代理 | -| 通用视频任务协议 | 支持将不同视频上游的任务提交、查询、进度、状态映射、错误消息和结果 URL 路径统一配置到渠道中；请求体透传和改写复用渠道设置，默认路径为 `/v1/videos/create` 与 `/v1/videos/{task_id}` | -| 协议转换与自定义上游 | 支持 OpenAI Compatible、Responses、Chat Completions、Claude Messages、Gemini 等格式之间的转换与适配，也支持配置合法授权的上游地址、路径覆盖和任务协议解析规则 | - -### AI Agent 治理 / AgentOps - -| 能力 | 说明 | -|------|------| -| Agent 令牌隔离 | 可为 Agent、工作流、插件、工具调用或用户创建独立 API Key，并配置模型范围、额度、过期时间和分组 | -| 模型访问控制 | 通过用户、令牌、分组、模型限制和渠道策略控制 Agent 能调用哪些模型、走哪些渠道、消耗多少额度 | -| 调用链路观测 | 提供请求日志、用量统计、渠道命中、耗时、错误和重试信息，帮助定位 Agent 调用失败、成本异常和上游波动 | -| 成本归因 | 支持按模型、渠道、用户、分组、令牌和节点维度统计成本与用量，方便核算不同 Agent、业务线或部署节点成本 | -| 管理员审计 | 私有部署场景可按合规要求启用管理员侧日志审计能力，普通用户日志接口会过滤管理员专用审计字段 | -| 运营看板 | 提供面向管理员的统计分析、用户管理、渠道管理、系统设置和运维分析能力 | - -### 成本、计费与可靠性治理 - -**模型价格表达式** - -- **一行表达式 = 一个 token 模型的完整计价规则**：阶梯定价、缓存命中、图像 / 音频 token 分项、分时折扣、按请求头或参数动态加价，全部写在同一行，适合维护复杂模型价格。 -- **价格即真实价格**：系数直接填写「美元 / 百万 token」，`p * 2.5` 就是输入每百万 token 2.5 美元，适合按上游价格表维护成本；传统倍率模式仍保持兼容。 -- **可视化 + 原始双模式编辑**：既可逐项填价格、按档位设条件，也可直接编辑表达式，并内置常见模型预设模板。 -- **统一 JSON 批量维护**：支持在一个 `Tiered billing JSON` 窗口中维护多个模型的分阶段计费规则，保存时原子更新 `billing_mode` 与 `billing_expr`，避免手动维护多个配置项时出现不同步。 -- **自动 token 归一**：按上游格式（OpenAI / Claude）和表达式实际用到的变量，自动从输入/输出中剥离缓存、图像、音频等子类别，避免重复计费；日志中可还原命中的计价档位与明细。 - -**任务计费、传统计费与可靠性** - -- 支持视频等异步任务的参数化 rate-card 计费，按模型、供应商、时长、质量、音频、视频输入等字段匹配单价；可通过 `task_billing_setting.rate_cards` 的 JSON 窗口统一维护，并用 `vendor` 字段区分 Sora、Veo、Seedance、Kling 等供应商分区。 -- 兼容按量、按次、缓存命中等计费模式，以及模型倍率、分组倍率、渠道倍率。 -- 支持预扣费、失败退款、异常处理和消费日志，适合长耗时 Agent 调用链路和异步多模态任务。 -- 支持渠道加权随机、失败重试、禁用渠道绕过和模型级路由，降低上游异常对应用和 Agent 的影响。 -- 支持 Redis 缓存与内存缓存，适配单机和多机部署。 - -### 性能与可扩展性治理 - -| 能力 | 说明 | -|------|------| -| 缓存与多节点扩展 | 单机可使用内存缓存，多机可接入 Redis；用户、令牌、渠道亲和、额度相关缓存减少重复数据库访问，并通过 `SESSION_SECRET`、`CRYPTO_SECRET`、`NODE_NAME` 保持会话、加密和日志归属一致 | -| 请求限流与容量保护 | 支持全局 API / Web 限流、关键接口限流、搜索限流、模型请求限流和按分组配置的模型请求配额；可使用 Redis 或内存计数器 | -| 流式与大请求控制 | 支持 `STREAMING_TIMEOUT`、`STREAM_SCANNER_MAX_BUFFER_MB`、`MAX_REQUEST_BODY_MB`、`MAX_FILE_DOWNLOAD_MB` 等配置，控制长流式响应、大行 SSE、解压后请求体和远程文件下载大小 | -| 中继连接调优 | 支持 `RELAY_TIMEOUT`、`RELAY_IDLE_CONN_TIMEOUT`、`RELAY_MAX_IDLE_CONNS`、`RELAY_MAX_IDLE_CONNS_PER_HOST` 配置上游 HTTP 连接池与超时策略 | -| 磁盘缓存与性能观测 | 系统性能设置可启用大请求体磁盘缓存、配置缓存阈值和容量；运维接口可查看 / 清理磁盘缓存，并可通过 Pyroscope 采集 CPU、内存、goroutine、mutex 和 block profile | -| 平滑退出与数据落盘 | 关闭进程时支持 `SHUTDOWN_TIMEOUT_SECONDS` 和 `QUOTA_DATA_CACHE_SAVE_TIMEOUT_SECONDS`，尽量在退出前完成 HTTP 关闭和额度缓存保存 | - -### 安全与组织管理 - -- 支持 JWT、WebAuthn/Passkeys、OAuth、OIDC、Telegram、Discord、LinuxDO 等登录方式。 -- 支持管理员、普通用户、分组、令牌和模型访问控制。 -- 支持请求体大小限制、流式超时控制、错误日志和运行状态检查。 -- 支持多机部署下的统一会话密钥、加密密钥和 Redis 共享缓存。 - ---- - -## 🆚 为什么使用网关 - -| 维度 | 直连各家官方 SDK / API | 通过 MAX API 网关 | -|------|------------------------|-------------------| -| 模型接入 | 每家一套 SDK、鉴权和参数 | 统一模型入口，一次接入，多模型复用 | -| 模型治理 | 模型清单、价格、权限和渠道分散在各平台 | 统一管理模型、渠道、映射、分组、额度和价格规则 | -| Agent 访问 | Agent 直接持有上游 Key，难以回收和限额 | 为 Agent 分配独立令牌，并限制模型、额度、过期时间和分组 | -| 协议差异 | 应用自行适配 Claude、Gemini、Responses 等格式 | 网关统一做协议转换和供应商适配 | -| 失败处理 | 应用自行实现重试、降级和错误归一 | 渠道失败自动重试、加权路由和错误处理 | -| 性能与扩展 | 应用自行处理超时、限流、连接池和缓存 | 网关集中提供流式超时、请求限制、Redis / 内存缓存、连接池调优和性能观测 | -| 成本统计 | 各平台账单分散，难以按用户或 Agent 核算 | 统一额度、计费、用量统计和消费日志，可按令牌和模型归因 | -| 审计边界 | 应用侧分散记录，权限和留存策略不统一 | 管理员侧统一审计入口，普通用户日志过滤管理员专用字段 | -| 私有化 | 密钥、日志和计费策略分散 | 自托管，自主掌控密钥、数据、日志和策略 | - ---- - -## 🧭 架构概览 - -MAX API 采用分层架构：应用、SDK 或 Agent 请求经统一入口进入，依次经过路由、中间件、控制器和业务服务层，最终由中继层适配到对应上游供应商；数据层和缓存层为模型治理、Agent 令牌治理、计费、日志、审计和任务状态提供持久化与加速能力。 - -![MAX API 系统架构图](./docs/images/MAX-API架构图.png) - -以下简图展示核心请求链路： - -```mermaid -flowchart LR - Client[客户端 / SDK / Agent] --> Router[Router
路由] - Router --> MW[Middleware
鉴权 · 限流 · 分发 · 日志] - MW --> Ctrl[Controller
请求处理器] - Ctrl --> Svc[Service
模型治理 · AgentOps · 计费审计] - Svc --> Relay[Relay
中继 / 协议转换] - Relay --> Adapters[Channel 适配器
OpenAI · Claude · Gemini · 国产平台 · 自定义上游] - Adapters --> Upstream[(上游模型服务)] - Svc --> Model[Model
GORM] - Model --> DB[(SQLite · MySQL · PostgreSQL)] - Svc --> Cache[(Redis · 内存缓存)] -``` - -### 目录结构 - -| 目录 | 职责 | -|------|------| -| `router/` | HTTP 路由，包含 API、relay、dashboard 和 web 入口 | -| `controller/` | 请求处理器，负责参数解析、鉴权后的业务入口和响应封装 | -| `service/` | 业务逻辑，包含模型治理、AgentOps、日志、计费、审计、任务、渠道和系统配置等能力 | -| `model/` | 数据模型与数据库访问，基于 GORM 兼容 SQLite、MySQL、PostgreSQL | -| `relay/` | AI API 中继、协议转换和供应商适配 | -| `relay/channel/` | 各供应商适配器，如 openai、claude、gemini、aws 等 | -| `middleware/` | 鉴权、限流、CORS、日志、请求分发和上下文处理 | -| `setting/` | 模型价格、任务计费、运营、系统、安全和性能配置 | -| `common/` | JSON、加密、Redis、限流、环境变量等共享工具 | -| `dto/` / `types/` | 请求、响应、错误和中继格式类型定义 | -| `constant/` | API 类型、渠道类型、上下文键等常量 | -| `i18n/` / `oauth/` / `pkg/` | 后端国际化、OAuth 实现和内部包 | -| `web/` | 前端主题容器，默认主题位于 `web/default/` | - -### 技术栈 - -| 层 | 技术 | -|------|------| -| 后端 | Go 1.25+、Gin、GORM v2 | -| 前端 | React 19、TypeScript、Rsbuild、Base UI、Tailwind CSS | -| 包管理 | Bun workspace | -| 数据库 | SQLite / MySQL ≥ 5.7.8 / PostgreSQL ≥ 9.6 | -| 缓存 | Redis + 内存缓存 | -| 鉴权 | JWT、WebAuthn/Passkeys、OAuth、OIDC | - ---- - -## 🤖 AI 模型与接口支持 - -> 实际可用模型取决于你的上游授权、渠道配置、模型映射和服务商支持情况。MAX API 的重点是把这些模型能力纳入统一治理，而不是提供上游模型服务本身。 - -| 类型 | 说明 | -|------|------| -| OpenAI-Compatible | Chat Completions、Embeddings、Images、Audio 等兼容接口，可作为多数应用和 Agent 的通用模型入口 | -| OpenAI Responses | Responses 格式请求、中继与 Responses ↔ Chat Completions 兼容转换，适合逐步接入新的 OpenAI 应用协议 | -| Claude Messages | Claude Messages 格式与 OpenAI 兼容格式转换，降低应用侧多协议维护成本 | -| Google Gemini | Gemini 聊天、文本，以及 `/v1/responses` 兼容转换能力 | -| Azure OpenAI | Azure OpenAI 与 Realtime 相关接口 | -| AWS Bedrock | Bedrock Runtime 相关模型接入 | -| 上游平台和应用生态 | AWS、Azure、Vertex、Ollama、Codex、Dify、RAGFlow、Kling、Seedance 等平台或应用形态可按渠道能力接入治理 | -| 国产模型与平台 | 内置 DeepSeek、通义千问 / 阿里云百炼、智谱 GLM、Kimi、豆包 / 火山引擎、腾讯混元、百度文心 / 千帆、讯飞星火、MiniMax、零一万物、硅基流动等适配器或兼容接入能力 | -| `rerank` | Cohere、Jina 等重排序模型，可用于检索增强和 Agent 检索链路 | -| Midjourney / Suno / Dify | 图像、音乐、工作流等服务适配 | -| 视频任务接口 | 支持 `/v1/videos/create`、`/v1/videos/{task_id}` 等视频生成任务的提交、请求体透传或参数覆盖、轮询、状态映射、结果代理和参数化任务计费 | -| 自定义上游 | 支持配置合法授权的上游接口地址、协议适配规则、Responses / Chat 转换、路径覆盖、状态映射、错误消息路径和任务结果解析 | - -### 支持的主要接口 +

+ QQ 群：950126533 • + 微信群：搜索 MAX-API +

-
-查看接口类别 - -- 聊天接口：`/v1/chat/completions` -- 响应接口：`/v1/responses` -- 图像接口：`/v1/images/*` -- 音频接口：`/v1/audio/*` -- 视频接口：`/v1/videos/*` -- 嵌入接口：`/v1/embeddings` -- 重排序接口：`/v1/rerank` -- 实时对话：OpenAI Realtime 兼容接口 -- Claude Messages：Claude 原生格式入口 -- Gemini：Google Gemini 格式入口 +| 社区入口 | 用途 | +|---|---| +| [MAX-API-Next GitHub](https://github.com/MAX-API-Next) | 关注社区项目、技术方向与开放协作 | +| [MAX API Issues](https://github.com/MAX-API-Next/MAX-API/issues) | 提交可复现问题、需求建议和兼容性变化 | +| [MAX API Releases](https://github.com/MAX-API-Next/MAX-API/releases) | 获取正式版与 Preview 版本动态 | +| [Ask DeepWiki](https://deepwiki.com/MAX-API-Next/MAX-API) | 快速检索和理解项目代码 | +| 技术与生态合作 | 联系 `maxapi@max-api.ai` | -
+### 我们正在寻找这些共建者 -### Reasoning Effort 支持 +- **模型与协议贡献者**：适配新模型、新供应商、Reasoning、工具调用和多模态任务协议。 +- **Agent 与应用开发者**：分享 Dify、RAGFlow、Codex、MCP、工作流和研究 Agent 的接入与治理实践。 +- **可靠性与安全工程师**：完善跨数据库测试、异步任务恢复、结算安全、缓存一致性和权限边界。 +- **文档与社区贡献者**：改进部署教程、FAQ、案例、翻译、可复现实验和新贡献者指引。 +- **研究者与评测开发者**：共建 Evidence、Evaluator、Detector、Runbook 和受控自治方案。
-查看示例模型命名 - -**OpenAI 系列：** +查看共建方向、协作原则与参与方式 -- `o3-mini-high` -- `o3-mini-medium` -- `o3-mini-low` -- `gpt-5-high` -- `gpt-5-medium` -- `gpt-5-low` +| 共建方向 | 适合的贡献 | +|---|---| +| 模型与供应商生态 | 模型/协议适配、兼容测试、模型列表与弃用变化、渠道配置模板 | +| AgentOps 与 AGI 应用治理 | Agent 接入示例、令牌与权限边界、成本治理和运行实践 | +| SmartOps 与 Evidence | 脱敏故障样本、指标口径、告警规则、数据质量说明、诊断与评测方法 | +| 可靠性、计费与安全 | 幂等结算、异步任务恢复、跨数据库回归、缓存一致性和高风险操作验证 | +| 文档、教程与国际化 | 部署教程、架构说明、FAQ、案例、翻译和新贡献者指引 | -**Claude 思考模型：** +协作时请尽量提供最小复现、版本、环境、脱敏日志或测试证据；协议、数据库和用户契约变更需要说明兼容性、迁移与回滚路径。请勿提交真实 API Key、客户数据、支付原始记录、私有日志或未经授权的数据。涉及资金、安全、密钥、生产数据或自动执行的贡献，需要更严格的测试、独立审查和明确责任人。 -- `claude-3-7-sonnet-20250219-thinking` +你可以从以下方式开始： -**Gemini 系列：** - -- `gemini-2.5-flash-thinking` -- `gemini-2.5-flash-nothinking` -- `gemini-2.5-pro-thinking` -- `gemini-2.5-pro-thinking-128` -- 也可以在 Gemini 模型名后追加 `-low`、`-medium`、`-high` 来控制思考力度。 +1. 提交一个可复现的问题、协议差异或模型兼容性变化。 +2. 为已有问题补充失败测试、跨数据库用例、前端回归或脱敏 Evidence。 +3. 完善模型/渠道配置、部署说明、FAQ、架构文档或多语言翻译。 +4. 分享经过脱敏的 Agent 接入、成本治理、SmartOps 和私有化部署实践。 +5. 提交 Evaluator、Detector、Runbook 或受控自治设计提案，并明确能力边界与风险。
---- - -## 🔧 治理配置 - -### 初始治理配置建议 - -1. 部署完成后进入控制台，创建或确认管理员账号。 -2. 配置系统设置、用户注册策略、登录方式和安全限制。 -3. 添加上游渠道，填写合法授权的 API Key、Base URL、模型列表、模型映射和渠道设置。 -4. 根据组织结构配置用户分组、令牌分组、模型限制、额度策略和价格规则，将模型能力纳入访问控制。 -5. 为应用、Agent 或工作流创建独立令牌，按业务线、环境或风险级别配置模型范围和额度。 -6. 在运营设置中配置失败重试、日志记录、缓存策略和消费统计。 -7. 如需管理员侧内容审计，应在合规前提下进入“系统设置 → 安全与限制 → 日志审计”启用，并确保“记录配额使用量（日志维护）”已开启。 - -### 渠道能力矩阵与配置校验 - -渠道新建或编辑时，系统会根据渠道类型展示能力矩阵，并给出实时配置校验结果。矩阵中的接口名称保留原始技术表述，例如 `chat/completions`、`responses`、`embeddings`、`rerank`、`video tasks`，说明文字使用中文，便于管理员判断当前渠道能承担哪些模型和任务。 - -配置校验覆盖以下常见问题： - -- 新建渠道缺少 API Key、模型列表为空、需要 Base URL 或额外配置但未填写。 -- Base URL 误填到 `/v1` 结尾，导致系统再次拼接上游路径。 -- `setting`、`param_override`、`header_override`、`settings` 等字段不是 JSON 对象。 -- Vertex AI 区域配置缺少 `default`，或服务账号密钥不是有效 JSON。 -- Codex 渠道凭证缺少 `access_token` 或 `account_id`。 -- 当前渠道不支持模型发现，但开启了上游模型检查或自动同步。 -- 视频任务查询路径缺少 `{task_id}`、`{operation_name}` 或 `{upstream_task_id}` 占位符。 - -### 通用视频任务协议 - -视频模型供应商的接口经常在路径、任务 ID、状态字段、进度字段、错误字段和结果 URL 字段上不一致。MAX API 将原先面向单一模型的任务协议能力扩展为通用视频任务协议，适用于 OpenAI、Ali、Gemini、MiniMax、Vertex AI、VolcEngine、Kling、Jimeng、Vidu、Doubao Video、Sora 等视频任务渠道。 - -支持的配置层级： - -- **仅路径覆盖**：只配置 `submit_path` 和 `query_path`，系统仍使用对应渠道的官方响应解析逻辑，适合只改上游路径的兼容渠道。 -- **完整协议解析**：设置 `task_protocol = "generic_video_task"`，同时配置任务 ID、状态、进度、结果 URL、错误消息和状态映射路径，适合非标准视频任务响应。 -- **请求体处理**：通用视频任务协议不再单独定义请求体生成模式。需要原样透传客户端 JSON 时使用渠道设置里的 `Pass Through Body`；需要字段改写、默认值或 header 联动时使用已有的 `Param Override`。 - -默认任务路径： - -```json -{ - "task_protocol": "generic_video_task", - "task_protocol_config": { - "submit_path": "/v1/videos/create", - "query_path": "/v1/videos/{task_id}", - "task_id_path": "task_id", - "status_path": "status", - "progress_path": "progress", - "result_url_paths": [ - "result.primary_url", - "result.urls.0", - "data.result.primary_url", - "url", - "video_url", - "download_url" - ], - "error_message_path": "error_message", - "status_map": { - "queued": "QUEUED", - "running": "IN_PROGRESS", - "succeeded": "SUCCESS", - "failed": "FAILURE" - } - } -} -``` - -查询路径支持 `{task_id}`、`{operation_name}`、`{upstream_task_id}`。其中 `{operation_name}` 可保留多段路径值，适合 Gemini / Vertex 风格的 operation 查询接口。视频内容可通过 `/v1/videos/{task_id}/content` 代理读取；在需要隐藏上游资源域名的部署中，建议让终端用户访问该内容代理地址，并配合鉴权、SSRF 防护和允许端口配置使用。 - -### 计费 JSON 维护 - -系统设置中的模型计费支持两类 JSON 统一维护入口： +配套文档：[MAX-API-Docs](https://github.com/MAX-API-Next/MAX-API-Docs)（部署、配置与使用说明）。 -- **分阶段计费 JSON**：通过 `Tiered billing JSON` 统一维护多个模型的 `{ enabled, expr }` 配置，保存时同步更新 `billing_mode` 与 `billing_expr`。 -- **任务 rate-card JSON**：通过 `task_billing_setting.rate_cards` 统一维护异步任务计费规则，可按 `vendor` 分区维护 Sora、Veo、Seedance、Kling 等视频模型的不同计费表。 +欢迎模型厂商、Agent/工作流项目、开源社区、研究者和企业工程团队开展技术共建。正式合作、联合发布或机构名义使用应经过双方明确授权。 -Seedance 2.0 等视频模型可按分辨率、视频输入等请求参数参与倍率或 rate-card 计算；使用透传或参数覆盖时，应确保最终提交给上游的字段与计费字段保持一致。 - -示例结构： - -```json -{ - "model-name": { - "enabled": true, - "expr": "len <= 200000 ? tier(\"standard\", p * 3 + c * 15) : tier(\"long_context\", p * 6 + c * 22.5)" - } -} -``` - -任务 rate-card 可按请求参数匹配价格： - -```json -{ - "vendor/model-name": { - "vendor": "kling", - "unit": "second", - "quantity_field": "duration", - "default_quantity": 5, - "strict": true, - "defaults": { - "quality": "std", - "has_audio": "false" - }, - "rows": [ - { - "id": "std_no_audio", - "match": { - "quality": "std", - "has_audio": "false" - }, - "unit_price": 0.6 - } - ] - } -} -``` - -### 常见运维入口 +> [!IMPORTANT] +> 面向公众提供生成式人工智能服务时，使用者应自行完成所在司法辖区要求的上游授权、备案许可、内容安全、实名、日志留存、税务、支付和用户协议等合规义务。日志审计和内容留存仅应在具备合法依据、明确告知、权限隔离和数据安全措施的场景下启用。 -| 功能 | 说明 | -|------|------| -| 渠道管理 | 配置上游供应商、模型映射、渠道权重、密钥、协议路径和状态，并通过能力矩阵与配置校验提前发现风险 | -| 模型与价格 | 维护模型列表、模型价格、表达式计费、分阶段计费 JSON、任务 rate-card JSON 和模型展示信息 | -| 令牌管理 | 为应用、Agent、工作流、工具调用或用户创建访问令牌并限制模型与额度 | -| 用户管理 | 管理用户、分组、余额、权限和状态 | -| 使用日志 | 查看调用记录、消耗、耗时、错误、渠道命中和管理员可见的审计信息 | -| 系统设置 | 管理安全限制、日志审计、模型定价、任务计费、运营策略、日志维护、支付和站点配置 | -| 数据看板 | 查看整体请求量、模型用量、消费趋势、渠道状态和 Agent 令牌成本 | +image ---- +## 🧠 面向 AGI 的技术方向 -## 🚢 部署 +AGI 应用不会长期依赖单一模型、单一协议或一次性请求。它们需要跨模型推理、工具调用、多模态任务、长期运行、成本约束、生产证据和可恢复的失败处理。MAX API 选择从这些可验证的工程问题出发，建设 AI Models and Agents governance 基础。 -### 部署要求 +| 技术方向 | 当前基础 | 对 AGI 应用的价值 | +|---|---|---| +| 多模型与多协议接入 | OpenAI Compatible、Responses、Claude Messages、Gemini、Realtime、多模态与异步任务协议 | 让应用和 Agent 面对相对稳定的入口，并能随模型生态变化持续迁移 | +| 推理与工具上下文兼容 | Reasoning Effort、工具定义、Tool Call、工具响应关联和多轮上下文转换 | 减少跨供应商切换时推理信息与工具调用语义丢失 | +| 治理控制平面 | 用户、令牌、模型范围、分组、路由、限流、额度、价格和管理员权限 | 为不同 Agent、环境和任务建立独立身份、访问边界与预算边界 | +| 可恢复计费与任务生命周期 | 预扣、最终结算、幂等记录、失败退款、异步任务轮询和人工对账状态 | 避免长任务、重试和异常窗口造成重复扣费、错误退款或不可追溯结果 | +| Evidence 与智能运维 | 日志、错误、重试、性能桶、活动告警、渠道/模型性能和结算证据 | 让诊断、评测和未来 Agent 建议建立在可追溯事实上，而不是仅依赖提示词推断 | +| 安全与组织治理 | Passkey、2FA、分作用域重新验证、会话撤销、审计和敏感操作限流 | 为高风险配置、凭据和运营操作保留明确的责任边界 | +| 受控自治与工程进化 | **长期蓝图**：Policy、Budget、Approval、Shadow、Canary、Rollback、隔离 Coding Workspace | 让自动化能力先被评测、约束和审计，再逐步进入低风险生产动作 | -| 组件 | 要求 | -|------|------| -| 容器引擎 | Docker / Docker Compose | -| 本地数据库 | SQLite，仅用于本地体验、开发或小规模测试；Docker 部署时需挂载 `/data` | -| 正式环境数据库 | MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6，并配置可靠的备份与恢复方案 | -| 缓存 | 单机可使用内存缓存，多机部署建议使用 Redis | -| 前端构建 | 使用 Bun workspace，需保留 `web/package.json` 与 `web/bun.lock` | -| 源码构建 | 使用仓库 `go.mod` 声明的 Go 版本（当前 Go 1.25.1+）和 `go.sum`；依赖或安全更新后运行 `go mod download`、`go mod verify` 并重新构建 | +### 技术原则 -### 推荐环境变量 +- **Evidence before Action**：先建立可验证事实，再进行诊断、建议或自动动作。 +- **Governance before Autonomy**：身份、权限、预算、审批、审计和回滚必须先于自治能力。 +- **One Billing Truth**：生产计费、额度与结算保持单一事实来源，不为 Agent 或插件建立第二套账务逻辑。 +- **Compatibility by Design**：持续支持 SQLite、MySQL、PostgreSQL、多供应商协议和可迁移的应用侧契约。 +- **Open Collaboration, Safe Boundaries**：开放协议适配、测试、文档、评测和治理方案，高风险生产、资金、密钥与发布动作继续由明确责任人审批。 -
-查看常用环境变量 - -| 变量名 | 说明 | 默认值 | -|--------|------|--------| -| `SESSION_SECRET` | 会话密钥，多机部署必须设置 | - | -| `CRYPTO_SECRET` | 加密密钥，使用 Redis 或多机部署时必须设置 | - | -| `SQL_DSN` | 数据库连接字符串 | - | -| `REDIS_CONN_STRING` | Redis 连接字符串 | - | -| `STREAMING_TIMEOUT` | 流式响应超时时间，单位秒 | `300` | -| `STREAM_SCANNER_MAX_BUFFER_MB` | 流式扫描器单行最大缓冲，图像 base64 等大响应可适当调大 | `64` | -| `MAX_REQUEST_BODY_MB` | 请求体最大大小，按解压后大小计算，超出返回 `413` | `32` | -| `AZURE_DEFAULT_API_VERSION` | Azure API 默认版本 | `2025-04-01-preview` | -| `ERROR_LOG_ENABLED` | 错误日志开关 | `false` | -| `NODE_NAME` | 节点名称，多机部署时用于日志定位和异步任务结算归属 | - | -| `PYROSCOPE_URL` | Pyroscope 服务地址 | - | -| `PYROSCOPE_APP_NAME` | Pyroscope 应用名 | `max-api` | -| `PYROSCOPE_BASIC_AUTH_USER` | Pyroscope Basic Auth 用户名 | - | -| `PYROSCOPE_BASIC_AUTH_PASSWORD` | Pyroscope Basic Auth 密码 | - | -| `PYROSCOPE_MUTEX_RATE` | Pyroscope mutex 采样率 | `5` | -| `PYROSCOPE_BLOCK_RATE` | Pyroscope block 采样率 | `5` | -| `HOSTNAME` | Pyroscope 标签中的主机名 | `max-api` | +### MAX API 2.0 技术亮点 -
+- **Evidence-driven SmartOps**：把资源告警、渠道/模型性能、数据质量状态和计费结算证据汇聚到统一运维入口，并保留人工审阅与真实财务状态之间的边界。 +- **面向先进模型协议持续演进**：增强 Responses、Claude Messages、Gemini 与 Ollama 的 Reasoning、缓存键、惩罚参数、工具定义和多轮 Tool Context 兼容。 +- **可恢复的计费与异步任务语义**：通过幂等 settlement、持久化 effect、任务 ID 和明确的 pending/manual 状态，避免异常重试导致重复扣费、错误退款或任务丢失。 +- **高风险操作分作用域重新验证**：Passkey、2FA、Telegram、API Token 与会话撤销采用 scope-bound step-up verification，并通过 `session_generation` 及时撤销旧会话。 +- **跨数据库与持续验证**：核心数据路径兼容 SQLite、MySQL 和 PostgreSQL；Go 测试、前端 Bun 测试、TypeScript 类型检查、JSON 包装规则和测试镜像同步共同构成发布门禁。 -### Docker Compose +## 💡 为什么需要 MAX API -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API +| 维度 | 直接连接多个供应商 | 使用 MAX API | +|---|---|---| +| 应用接入 | 分别维护 SDK、协议、鉴权和错误格式 | 应用侧使用相对稳定的统一入口 | +| 模型切换 | 修改代码、密钥和部署配置 | 通过渠道、模型映射、分组和路由调整 | +| 可用性 | 每个应用自行处理重试和上游故障 | 集中配置权重、优先级、失败重试和切换 | +| 权限与密钥 | 凭据散落在应用和环境变量中 | 集中管理令牌、模型范围、额度和有效期 | +| 成本核算 | 多家账单分散，难以归因 | 按用户、令牌、模型、渠道和分组统计 | +| 故障排查 | 日志分散，跨供应商定位困难 | 在网关侧统一观察请求、错误、重试和耗时 | -# 修改 docker-compose.yml： -# - 更换 PostgreSQL / MySQL / Redis 默认密码 -# - 按需设置 SESSION_SECRET、CRYPTO_SECRET、NODE_NAME -# - 生产环境建议配置反向代理与 HTTPS -docker compose up -d -``` +一句话概括：**供应商负责提供模型，Agent 框架负责编排业务，MAX API 负责统一接入并守住治理边界。** -### Docker 命令 +## 🚀 快速开始 -**SQLite：** +本地体验默认使用 SQLite，只需 Docker： ```bash -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest -``` +MAX_API_IMAGE=cscitechtop/max-api:latest@sha256:006d5d86887a261baab4d71ec3797d429e3771a4836e5899734aee0e7f66f2ab -**MySQL：** +docker pull "$MAX_API_IMAGE" -```bash -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e SQL_DSN="root:123456@tcp(mysql:3306)/max-api" \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest +docker run --name max-api -d --restart always -p 127.0.0.1:3000:3000 -e TZ=Asia/Shanghai -v ./data:/data "$MAX_API_IMAGE" ``` -### 从源码构建镜像 +启动后访问： -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API -docker build -t cscitechtop/max-api:latest . -``` +接下来完成三件事： -> [!NOTE] -> `Dockerfile` 会在镜像构建中下载 Go 模块。宿主机直接构建或依赖 / 安全更新后，请保持 `go.mod` 与 `go.sum` 成对提交，先运行 `go mod download && go mod verify`，再重新构建二进制或镜像；需要刷新基础镜像时可使用 `docker build --pull --no-cache -t cscitechtop/max-api:latest .`。 +1. 创建或确认管理员账号。 +2. 添加一个具有合法授权的上游渠道和 API Key。 +3. 创建访问令牌，把应用中的 Base URL 指向 MAX API。 > [!TIP] -> 前端使用 Bun workspace。构建上下文中必须保留 `web/package.json`、`web/bun.lock` 和 `web/default/package.json`，否则 `catalog:` 依赖无法解析。 - -### 多机部署注意事项 - +> 生产环境建议使用正式版。Preview 版本用于测试和灰度验证，升级前请备份数据库并准备回滚方案。 +> > [!WARNING] -> - 必须设置相同的 `SESSION_SECRET`，否则不同节点之间登录状态不一致。 -> - 使用共享 Redis 时必须设置相同的 `CRYPTO_SECRET`，否则加密数据无法解密。 -> - 多节点建议设置稳定的 `NODE_NAME`，便于在日志、审计信息和异步任务结算中定位来源节点。 -> - 生产环境应使用外部数据库、外部 Redis、HTTPS 反向代理和可靠的备份策略。 +> SQLite 适合本地体验、开发和小规模测试。正式环境建议使用仍在供应商安全支持周期内的 MySQL（建议 8.4 LTS）或 PostgreSQL（建议 14+），并配置 Redis、HTTPS、备份和恢复方案。项目兼容性下限仍为 MySQL ≥ 5.7.8、PostgreSQL ≥ 9.6，但不建议将其用于生产。 ---- +## ✨ 当前能力 -## 🗺️ 路线图 +以下能力已经在当前系统中提供： -以下为方向性规划，会根据维护节奏、真实场景和社区需求调整，不构成时间承诺。 +| 能力 | 主要用途 | +|---|---| +| 统一模型入口 | 接入 OpenAI Compatible、Responses、Claude Messages、Gemini、Realtime 和多模态任务接口 | +| 多供应商路由 | 管理渠道、权重、优先级、分组、模型映射、失败重试和跨供应商切换 | +| 身份与访问控制 | 管理用户、令牌、模型范围、分组、额度、有效期、限流和管理员权限 | +| 成本与计费 | 支持倍率、固定价格、表达式计费、异步任务 rate-card、预扣费、结算和失败退款 | +| 日志与审计 | 按用户、令牌、模型、渠道、分组和节点查看使用、错误、重试和管理操作 | +| 智能运维中心 | 集中查看活动告警、渠道性能、模型性能、系统信息和计费结算对账证据，辅助管理员发现、定位和审阅生产问题 | +| 私有化部署 | 支持 SQLite、MySQL、PostgreSQL、Redis、多节点和独立日志库 | +| 上游扩展 | 支持协议适配、路径覆盖、参数/Header 覆盖、模型发现和任务状态映射 | -- **模型治理深化**：围绕模型目录、模型价格、模型权限、模型映射、模型能力标签和供应商变更，持续增强治理能力。 -- **AgentOps 深化**：围绕 Agent、工具调用、工作流和 MCP 风格工具 / 服务接入，持续优化调用链路、成本归因、异常定位和治理能力。 -- **多模态任务治理**：增强图像、视频、音频和实时交互任务的计费、限流、状态追踪和结果代理。 -- **协议转换增强**：持续完善 OpenAI Compatible、Responses、Claude Messages、Gemini 等协议之间的转换。 -- **国产模型与平台跟踪适配**：跟进国产模型、云平台、价格规则和 API 协议变化，沉淀可复用的渠道、价格和任务协议配置。 -- **供应商适配模板化**：让路径覆盖、任务协议、状态映射、错误解析和结果解析更容易配置和复用。 -- **治理审计与运营优化**：完善请求链路、成本追踪、错误分析、管理员审计、日志留存和运维报表。 -- **组织级运营能力**：增强多租户、分组、账单、权限、风控和私有化部署体验。 +### 适用场景 -欢迎在 [GitHub Issues](https://github.com/MAX-API-Next/MAX-API/issues) 提出需求、问题和改进建议。 +- **团队或组织内部模型网关**：统一管理用户、令牌、模型、供应商、权限和费用。 +- **AI 应用与 Agent 运行底座**：为应用、Agent 和工作流提供模型访问控制、成本归因与异常定位。 +- **多供应商容灾与迁移**：通过模型映射、加权路由、失败重试和灰度切换降低单一上游风险。 +- **多模态任务治理**：统一管理图像、音频、视频、嵌入、重排序和实时对话接口。 +- **私有化与合规运营**：自主管理密钥、数据、日志、审计、价格和部署环境。 ---- +## 🩺 智能运维中心 -## ❓ 常见问题 +**智能运维中心是 MAX API 2.0 的重大更新，也是项目从统一模型网关走向 AGI 原生治理与运营基础设施的关键一步。** -
-MAX API 会提供模型服务或 API Key 吗？ +它将生产观测、资源告警、模型与渠道性能、系统信息和计费结算对账集中到统一管理员入口。当前能力强调“看见问题、保留证据、通知管理员、受控审阅”，并不是会自动修改渠道、路由、余额或主机的自治 Agent。 -不会。MAX API 是模型与 Agent 工作负载的网关治理层，不提供上游模型账号、API Key、基础模型训练能力或模型服务本身。使用者需要自行获得合法授权的上游服务。 +| 模块 | 当前提供的内容 | +|---|---| +| 活动告警 | 对当前节点的 CPU、内存和磁盘持续超阈值进行去重告警，在恢复时发送恢复通知；复用管理员已有的 Email、Webhook、Bark 或 Gotify 配置 | +| 渠道性能 | 查看请求与错误、消耗额度、估算成功率、日志延迟、重试、探测延迟和最近观测时间；详情可查看该渠道最近 24 小时的模型与分组表现 | +| 模型性能 | 汇总所有模型的渠道数、请求与错误、消耗额度、估算成功率、日志延迟、吞吐量和重试；详情提供各分组性能、延迟趋势和可用率趋势 | +| 计费结算对账 | 展示 `pending` / `manual` 正向最终结算、未结资金、重试和错误证据；根管理员可配置默认用户阻断策略，管理员可按 `id + revision` 原子批量审阅并关闭告警 | +| 系统信息 | 查看节点、运行实例和系统任务等信息；该模块继续要求超级管理员权限 | -
+活动告警页面每 5 秒读取一次当前告警状态，但不会触发新的检测或修复动作。渠道与模型列表默认查询最近 1 小时，管理员可以输入 `1–168` 小时的自定义窗口；它们不会自动反复统计大日志库，只有点击“应用筛选”或“刷新”时才执行查询，详情数据在打开时按需加载。 -
-MAX API 和 Agent 框架是什么关系？ - -MAX API 不替代 Dify、LangChain、MCP Server、工作流引擎或业务 Agent 应用。它位于这些应用与上游模型服务之间，负责模型接入、令牌隔离、成本核算、路由容灾、日志观测和管理员审计等治理能力。 +计费结算对账把财务恢复状态与运维告警状态严格分离：“审阅并关闭”只记录管理员审阅并关闭当前告警，不会把结算标记为 `applied`，不会修改余额、已应用差额或 effect 状态。批量审阅绑定当前财务 revision；刷新后记录发生变化时，旧选择会自动失效，避免使用过期证据作出操作。 -
+> [!NOTE] +> 当前生产性能主要聚合既有 Consume/Error 日志和 `perf_metrics`：估算成功率并非完整的 Relay Attempt 成功率，吞吐量与趋势属于性能桶级近似值。日志关闭、历史数据缺失、采集关闭、窗口无样本或查询失败时，页面会显示相应的数据质量状态。 +> +> 活动告警依赖性能监控和资源阈值配置；阈值设为 `0` 时表示关闭该资源告警，需连续两个有效样本才会触发。状态与通知队列只保存在当前进程内存中：进程重启后不会保留，多节点也不会自动合并为跨节点 Incident。渠道、模型和系统观测保持只读；结算审阅仅更新审阅元数据与用户阻断策略，不执行资金结算。智能运维中心不会自动测试、禁用、调权、切换渠道或修复主机。 -
-为什么强调 AI 模型治理？ +这一阶段的价值，是先完成“看见问题、通知管理员、提供证据、受控审阅”的闭环，为后续统一 Evidence、诊断 Agent、Evaluator 和受控自动化建立基础。 -在真实组织中，模型不只是一个 API 名称，还涉及供应商、价格、上下文长度、协议格式、权限范围、稳定性和审计边界。MAX API 的价值在于把这些分散变量统一配置、统一观察和统一核算。 +## 🔌 模型、接口与扩展 -
+> 实际可用能力取决于你的上游授权、渠道配置、模型映射和供应商支持。MAX API 负责治理这些能力，不提供模型服务本身。 -
-支持哪些数据库？ +| 类别 | 接口或能力 | +|---|---| +| 通用模型接口 | Chat Completions、Responses、Embeddings、Rerank、Images、Audio、Video | +| 原生与实时协议 | Claude Messages、Google Gemini、OpenAI Realtime 等入口 | +| 推理与工具调用 | 支持 Reasoning Effort、函数工具、Tool Call ID、工具名称和多轮工具响应关联，并按不同上游能力进行协议转换 | +| 异步任务 | 任务提交、轮询、状态映射、结果代理和参数化计费 | +| 自定义上游 | Base URL、路径、参数、Header、状态字段和结果字段映射 | -支持 SQLite、MySQL ≥ 5.7.8 和 PostgreSQL ≥ 9.6。本地体验可使用 SQLite；生产环境建议使用 MySQL 或 PostgreSQL，并做好备份。 +覆盖 OpenAI、Claude、Gemini、Azure、AWS Bedrock、Vertex AI、Ollama 及多种国内模型平台，也可治理 Codex、Dify、RAGFlow 和多模态任务服务。具体支持范围以当前版本和渠道类型为准。 -
+### 系统工作方式与技术栈 -
-能否从 New API / One API 迁移？ +![MAX API 系统架构图](./docs/images/MAX-API架构图.png) -项目兼容 New API 与原版 One API 的主要数据结构，通常可以复用既有数据。迁移前仍建议备份数据库，并在测试环境验证渠道、倍率、用户、令牌和日志数据。 +```text +应用 / SDK / Agent + → 统一接口与身份鉴权 + → 模型权限、限流、预算和安全检查 + → 渠道选择、映射与失败重试 + → 上游协议适配 + → 可恢复结算、Evidence、日志和审计 + → 智能运维中心与管理员治理 +``` -
+后端使用 Go、Gin 和 GORM，前端使用 React 19、TypeScript、Base UI 与 Tailwind CSS，数据层兼容 SQLite、MySQL 和 PostgreSQL，并可使用 Redis 与独立日志库。供应商协议适配位于独立 Relay/Channel 层，计费与结算集中在统一服务边界中，管理端通过 SmartOps 展示只读观测和受限治理入口。 -
-多机部署需要注意什么？ +## 🛡️ 治理与运营 -必须统一 `SESSION_SECRET`。如果使用共享 Redis，也必须统一 `CRYPTO_SECRET`。否则可能出现登录状态不一致、缓存数据无法解密或任务状态异常。 +生产环境建议按以下顺序配置： -
+1. 配置登录、安全限制和用户注册策略。 +2. 添加合法授权的上游渠道，确认模型、能力和协议配置。 +3. 按团队、业务或环境设置分组、令牌、模型范围、额度和价格。 +4. 为每个应用、Agent 或环境使用独立令牌，避免共享凭据和成本归属。 +5. 配置重试、日志与告警，通过数据看板和智能运维中心持续观察。 -
-图像生成、流式响应或大响应被截断怎么办？ +渠道能力校验、表达式计费、通用任务协议、管理员审计和性能参数等高级配置，请查看 [详细文档](https://docs.max-api.ai)。 -可调大 `STREAM_SCANNER_MAX_BUFFER_MB`。4K 图像、base64 图片、长流式响应等场景可能需要更大的扫描缓冲。 +## 🧭 演进路线 -
+MAX API 将继续以 **AI Models and Agents governance** 为核心，从统一网关、智能运维和可恢复结算出发，逐步建设面向 AGI 应用的 Evidence、评测、策略与受控执行能力。长期方向不是让一个无边界 Agent 接管生产系统，而是建立可验证、可审批、可停止、可回滚的工程闭环。 -
-请求体过大返回 413 怎么办？ +| 阶段 | 状态 | 重点 | +|---|---|---| +| 统一网关与智能运维 | **现已提供** | 接入、鉴权、路由、计费、日志、资源告警、渠道/模型性能、系统信息和计费结算对账 | +| Evidence 事实层 | **近期建设** | 统一模型请求、系统日志、指标、Task、路由、策略、结算和审计事件，向 Agent 提供脱敏、限权、只读接口 | +| 开放评测与治理模板 | **规划中** | 与社区沉淀模型/协议兼容测试、匿名故障样本、评测集、Runbook、Detector 和行业治理模板 | +| 受控自治运维 | **长期蓝图** | 在 Policy、Budget、Approval、Shadow、Canary 和 Rollback 约束下评估低风险自动动作 | +| 受控能力进化 | **长期蓝图** | 在隔离 Coding Workspace 中生成、测试和审阅候选改进，不直接修改生产系统 | +| AGI 工程闭环 | **长期方向** | 将 Evidence、评测、治理策略、人工审批与可回滚执行连接为可验证闭环 | -调整 `MAX_REQUEST_BODY_MB`。该限制按解压后的请求体大小计算，用于防止超大请求或 zip bomb 导致内存暴涨。 +MAX API 不是基础模型，也不宣称当前已经实现 AGI 或自治运维。路线图中的长期能力只有在证据、权限、预算、审批和回滚边界完善后才会逐步验证。 -
+## 🚢 Preview 部署 -
-用户能看到管理员日志审计中的输入输出内容吗？ +以下步骤用于 Preview 版本的测试和灰度验证。生产环境请改用正式版，并沿用相同的校验和回滚流程。 -正常用户日志接口会过滤管理员专用字段，普通用户无法在自助使用日志中看到管理员审计内容。数据库管理员、系统管理员或拥有管理员日志接口权限的人仍可能访问相关数据，因此应按合规要求严格控制权限。 +推荐使用 Docker Compose： -
- -
-为什么 Docker 构建时提示 `catalog:` 依赖无法解析？ - -前端使用 Bun workspace，`catalog:` 依赖定义在 `web/package.json`。构建时不能用 `web/default/package.json` 覆盖 workspace 根 `package.json`，并且需要保留 `web/bun.lock`。 - -
- ---- +```bash +MAX_API_VERSION=v2.0.0-smartops.pre1 +MAX_API_COMMIT=b7096156549edc930ca244891afb1ba5632dbe8f +git clone --branch "$MAX_API_VERSION" --depth 1 https://github.com/MAX-API-Next/MAX-API.git +cd MAX-API -## 🔗 相关项目 +actual_commit="$(git rev-parse HEAD)" +if [ "$actual_commit" != "$MAX_API_COMMIT" ]; then + echo "Unexpected commit: $actual_commit" >&2 + exit 1 +fi -| 项目 | 说明 | -|------|------| -| [One API](https://github.com/songquanpeng/one-api) | MIT 协议 | -| [New API](https://github.com/QuantumNous/new-api) | AGPLv3 协议 | -| [Midjourney-Proxy](https://github.com/novicezk/midjourney-proxy) | Apache-2.0 协议 | -| [Suno API](https://github.com/Suno-API/Suno-API) | MIT 协议 | +# 修改 docker-compose.yml 中的数据库、Redis 密码和密钥 +docker compose up -d +``` -### 配套工具 +### 部署检查 -| 项目 | 说明 | -|------|------| -| [max-api-key-tool](https://github.com/MAX-API-Next/MAX-API-key-tool) | Key 额度查询工具 | -| [max-api-horizon](https://github.com/MAX-API-Next/MAX-API-horizon) | MAX API 高性能优化版 | +| 组件 | 建议 | +|---|---| +| 数据库 | 使用仍在供应商安全支持周期内的 MySQL（建议 8.4 LTS）或 PostgreSQL（建议 14+），并配置备份与恢复 | +| 缓存 | 单机可使用内存缓存，多节点部署建议使用 Redis | +| 入口 | 配置 HTTPS 反向代理、请求大小限制和可信网络策略 | +| 密钥 | 显式配置随机 `SESSION_SECRET`；`CRYPTO_SECRET` 为可选覆盖项，未设置时回退到 `SESSION_SECRET`，如单独设置则需在 Redis/多节点场景统一 | +| 节点 | 每个节点设置稳定且唯一的 `NODE_NAME` | +| 日志 | 根据合规和运维需要配置 `LOG_SQL_DSN`、清理与保留策略 | ---- +多节点必须统一 `SESSION_SECRET`，并为每个节点使用不同的 `NODE_NAME`。`CRYPTO_SECRET` 为可选覆盖项，未设置时使用 `SESSION_SECRET`；如显式设置，则所有节点必须使用相同值。独立日志库使用 `LOG_SQL_DSN`；错误性能统计需要按需启用 `ERROR_LOG_ENABLED`。完整环境变量和源码构建说明见 [详细文档](https://docs.max-api.ai)。 -## 📚 文档与支持 - -| 资源 | 链接 | -|------|------| -| 官方文档 | [MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) | -| 问题反馈 | [GitHub Issues](https://github.com/MAX-API-Next/MAX-API/issues) | -| 最新发布 | [Releases](https://github.com/MAX-API-Next/MAX-API/releases) | -| DeepWiki | [Ask DeepWiki](https://deepwiki.com/MAX-API-Next/MAX-API) | - -### 二次开发与社区鸣谢 - -如果你基于本项目进行二次开发并仅供自用，欢迎在项目主页、页脚或“关于”页面等明显位置，任选一种方式保留项目来源或社区鸣谢： - -- 添加项目地址：[MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) -- 鸣谢社区：[MAX-API-Next](https://github.com/MAX-API-Next) - -参考前端嵌入代码（React / Tailwind CSS，可按需保留其中一项）： - -```tsx -

- 基于{' '} - - MAX-API-Next/MAX-API - {' '} - 二次开发 · 感谢{' '} - - MAX-API-Next 社区 - -

-``` +## 🤝 项目来源、致谢与二次开发 -满足上述任一展示要求并保持链接清晰可见，即自动获得本项目的临时商用授权，无需另行申请或等待确认。该授权为非永久授权，仅在持续满足展示要求期间有效；有效期及后续调整以项目方在本 README 或官方社区发布的最新说明为准。 +MAX API 基于 [One API](https://github.com/songquanpeng/one-api) 和 [New API](https://github.com/QuantumNous/new-api) 的开源成果持续开发。感谢上游项目、贡献者，以及所有参与协议适配、测试、文档、翻译与问题反馈的社区成员。 -本项目基于 [One API](https://github.com/songquanpeng/one-api) 和 [New API](https://github.com/QuantumNous/new-api) 开发。现阶段，MAX API 主要在上述项目基础上持续增强 AI API 网关与治理能力、扩展功能并修复问题。商业使用本项目时，还须分别遵守 One API 的 MIT 许可证与 New API 的 AGPLv3 许可证，具体以各上游项目的 `LICENSE` 文件为准；本项目提供的临时商用授权不替代、也不免除相关上游项目的开源许可义务。 +根据 [NOTICE](./NOTICE) 和 AGPLv3 第 7 节，包含用户界面的修改版本必须在显著可见的“关于”、法律声明、页脚或署名位置同时保留： -如不再满足展示要求，或临时授权到期、被公告调整或终止，仍需按 AGPLv3 或项目方另行书面授权使用本项目。如需长期商用授权，请联系：maxapi@max-api.ai。 +- MAX API 原项目链接：[MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) +- MAX API NOTICE 中的原文署名：`Frontend design and development by MAX API contributors.` +- New API 上游项目链接：[QuantumNous/new-api](https://github.com/QuantumNous/new-api) +- New API NOTICE 中的原文署名：`Frontend design and development by New API contributors.` +- 明确的修改声明及相关修改日期 -欢迎提交 Issue、改进文档、补充供应商适配经验、完善部署方案或贡献代码。 +可以额外鸣谢 [MAX-API-Next 社区](https://github.com/MAX-API-Next)，但社区鸣谢不能替代上述必需的项目链接、原文署名和变更标记。 ---- +持续满足上述展示与 NOTICE 要求，即自动获得本项目的非永久临时商用授权，无需另行申请或等待确认；该授权仅覆盖 MAX API 项目方有权授权的部分，不免除 AGPLv3 或 One API、New API 等上游项目的许可义务。最新条件以正式 README 与社区公告为准。 ## 📜 许可证 -本项目采用 [GNU Affero 通用公共许可证 v3.0 (AGPLv3)](./LICENSE) 授权。 - -除默认的 AGPLv3 授权外，符合上文“二次开发与社区鸣谢”条件的自用二开项目，可按该说明自动获得非永久的临时商用授权。该临时授权仅覆盖 MAX API 项目方有权授权的新增与修改部分，并不包含或代替 One API、New API 等上游项目的许可授权。 +本项目采用 [GNU Affero 通用公共许可证 v3.0（AGPLv3）](./LICENSE) 授权。 -如果你修改并通过网络向用户提供本项目服务，请理解并遵守 AGPLv3 对应源码提供等义务。商业合作、机构合作或其他授权问题，请联系：maxapi@max-api.ai。 +临时商用授权仅覆盖 MAX API 项目方有权授权的新增与修改部分，不包含、替代或免除 One API、New API 等上游项目的许可义务。商业使用时，请同时遵守 One API 的 MIT 许可证、New API 的 AGPLv3 许可证及各上游项目的最新许可要求。 +如果你修改并通过网络向用户提供本项目服务，请理解并遵守 AGPLv3 对应的源码提供等义务。长期商用授权、机构合作或其他授权问题，请联系：maxapi@max-api.ai。 --- @@ -769,9 +356,9 @@ MAX API 不替代 Dify、LangChain、MCP Server、工作流引擎或业务 Agent ### 💖 感谢使用 MAX API -如果这个项目对你有帮助，欢迎给我们一个 ⭐ Star。 +如果这个项目对你有帮助，欢迎给我们一个 ⭐ Star、关注 Releases、提交可复现 Issue，或参与 MAX-API-Next 社区共建。 -**[官方文档](https://github.com/MAX-API-Next/MAX-API)** • **[问题反馈](https://github.com/MAX-API-Next/MAX-API/issues)** • **[最新发布](https://github.com/MAX-API-Next/MAX-API/releases)** +**[项目仓库](https://github.com/MAX-API-Next/MAX-API)** • **[参与共建](https://github.com/MAX-API-Next/MAX-API/issues)** • **[最新发布](https://github.com/MAX-API-Next/MAX-API/releases)** • **[MAX-API-Next 社区](https://github.com/MAX-API-Next)** Built with ❤️ by MAX-API-Next diff --git a/README.zh_CN.md b/README.zh_CN.md index 6bd672dd..4bf56c80 100644 --- a/README.zh_CN.md +++ b/README.zh_CN.md @@ -1,10 +1,14 @@ -
+# MAX API -![max-api](/web/default/public/logo.png) +
-# MAX API +![MAX API](./web/default/public/logo.png) + +**面向 AGI 应用时代的 AI Models 与 Agents 治理、智能运维和开放协作基础设施** + +**MAX API 2.0：开启智能运维时代 · 从统一模型网关走向 AGI 原生治理与运营** -🍥 **AI 模型治理、AgentOps 与 AGI 应用服务基础设施** +[查看 MAX API 2.0 Preview 发布说明](https://github.com/MAX-API-Next/MAX-API/releases/tag/v2.0.0-smartops.pre1)

简体中文 | @@ -30,745 +34,321 @@

- 项目定位 • - 发布渠道 • - 治理框架 • - 适用场景 • + ⭐ Star 项目 • + 💬 加入社群 • + 📚 查看文档 • + 🚀 获取版本 +

+ +

+ 加入社区 • 快速开始 • - 核心能力 • - 治理配置 • - 架构概览 • - 模型与接口 • - 部署 • - FAQ • - 许可证 + 为什么需要 • + AGI 技术方向 • + 当前能力 • + 智能运维 • + Preview 部署

--- -## 📝 项目说明 - -MAX API 是由来自科研机构和高校的 AGI 爱好者组织发起、维护和长期运营的 AI 模型治理、AgentOps 与应用服务基础设施项目，面向开发者、研究者、团队和组织提供稳定、可复用的服务层能力。项目关注 AI 应用落地后的持续运营问题：模型越来越多、供应商接口频繁变化、Agent 调用链路变长、成本和审计压力增加。MAX API 在应用、Agent、用户、组织和上游模型服务之间提供统一的接入、鉴权、路由、计费、观测和治理层，让 AI 应用更稳定、更可控地运行。 - -换句话说，MAX API 不只是请求转发器，而是面向 AI-ready 应用和 Agent 工作负载的可运营网关：在统一模型协议与供应商差异的同时，把突发流量、长流式响应、大请求体、多节点缓存、成本审计和性能观测放进同一套治理边界。 - -持续投入方向： - -- **AI 模型治理**：持续跟踪 OpenAI、Azure OpenAI、AWS Bedrock、Vertex AI、Ollama，以及 DeepSeek、通义千问 / 阿里云百炼、智谱 GLM、Kimi、豆包 / 火山引擎、腾讯混元、百度文心 / 千帆、讯飞星火、MiniMax、零一万物、硅基流动等模型与平台的模型更新、接口变化、参数差异、价格规则和任务协议；同时关注 Dify、RAGFlow、Kling、Seedance 等应用和多模态生态的接入形态，通过渠道、模型映射、协议转换、路径覆盖和可配置任务协议，把分散模型能力纳入统一治理。 -- **AI Agent 治理 / AgentOps**：围绕 Agent、工作流和工具调用场景，持续完善令牌治理、模型访问控制、调用追踪、成本归因、异常定位和日志审计，并为后续 MCP 风格工具 / 服务接入预留统一治理边界，帮助 Agent 应用在真实业务中更可观测、更可运营。 -- **渠道配置治理**：在渠道新建和编辑界面提供渠道能力矩阵与配置校验，直观展示 `chat/completions`、`responses`、`embeddings`、`rerank`、`video tasks`、模型发现等能力，并提前提示 Base URL、JSON 配置、Vertex AI 区域、Codex 凭证、视频任务占位符等常见配置风险。 -- **运营优化与成本治理**：持续优化渠道路由、失败重试、限流、预扣费、失败退款、日志观测、成本统计和运维分析；文本与多模态 token 场景可使用表达式计费和统一 JSON 配置，视频等异步任务场景可使用参数化 rate-card，让模型成本和 Agent 调用成本更直观、可核算、可批量维护。 - -> [!IMPORTANT] -> - 面向公众提供生成式人工智能服务时，使用者应遵守[《生成式人工智能服务管理暂行办法》](http://www.cac.gov.cn/2023-07/13/c_1690898327029107.htm)等监管要求，并自行完成所在司法辖区要求的备案、许可、内容安全、实名、日志留存、税务、支付和上游授权等合规义务。 -> - 日志审计、内容留存等敏感能力应仅在具备合法依据、明确告知、权限隔离和数据安全措施的场景下启用。 -> - MAX API 提供模型与 Agent 工作负载的网关治理层，不提供上游模型账号、密钥、基础模型训练能力，也不替代 Dify、LangChain、MCP Server 等 Agent 编排或应用开发框架。 - ---- - -## 🚦 发布渠道 - -MAX API 当前版本发布分为正式版和 Preview 预览版。Preview 预览版用于提前开放新能力和修复，便于社区与部署者在真实环境中验证兼容性、稳定性和安全性；正式版会在对应 Preview 预览版稳定运行 1 周后发布，以降低生产环境升级风险，保障系统安全性和可靠性。 +MAX API 位于应用、Agent 与上游模型服务之间，是统一的模型网关、治理控制平面和运营入口。MAX-API-Next 社区围绕 AGI 工程化持续建设本项目，并面向开发者、研究者、企业工程团队、高校技术爱好者和开源贡献者开放协作。我们的目标是建设 AGI 应用真正需要的模型接入、权限、成本、Evidence、智能运维和安全控制基础。 -生产环境建议优先使用正式版；需要提前验证新功能、修复或兼容性变化时，可在测试环境或灰度环境使用 Preview 预览版，并在升级前做好数据库备份和回滚预案。 +我们将在 AGI 领域：**持续交付先进而可验证的技术、将真实生产问题沉淀为开放工程能力、建立能够共同研究和贡献的社区。** -### 💬 社区访问 +## 🌐 加入 MAX-API-Next 社区 -- 🌐 GitHub 地址：[https://github.com/MAX-API-Next](https://github.com/MAX-API-Next) -- 👥 社群交流：QQ(950126533) | 微信群(搜索MAX-API) - ---- +MAX API 不只是一个代码仓库，也是一项面向 AI Models、Agents、AgentOps 与 AGI 工程化的长期开放协作。无论你正在部署模型网关、开发 Agent、适配新模型、研究评测与治理，还是愿意改进文档和国际化，都欢迎加入社群交流并参与共建。 -## 🎯 项目定位 +**加入社群，你可以更快获取版本动态、模型与协议变化、部署经验、问题排查线索和社区共建机会。** -在 AGI 应用时代，MAX API 聚焦于开放的 AI 模型治理和 AI Agent 治理基础设施，建设让开发者和组织能够稳定运行 AI 应用与 Agent 工作负载的服务、治理和运营层： - -- **模型治理平面**：统一管理模型入口、渠道、供应商、协议格式、模型映射、价格规则、任务协议和多模态接口。 -- **AgentOps 控制平面**：不替代 Agent 编排框架，而是在网关层为 Agent 工作负载提供令牌治理、模型访问控制、调用日志、成本追踪、异常定位和运营分析。 -- **渠道配置平面**：通过能力矩阵、表单校验、模型发现和协议模板，降低新增上游渠道、迁移供应商和维护非标准接口时的误配置风险。 -- **协议与供应商适配层**：持续跟踪海外官方接口、国产模型平台接口（DeepSeek、通义、智谱、火山引擎、百度千帆等）以及各类 OpenAI 兼容 / 非标准接口的变化，并规范化为稳定的应用侧接口。 -- **成本、额度与可靠性治理**：支持渠道路由、加权分发、失败重试、限流、预扣费、失败退款，以及表达式计费、固定价格、任务 rate-card、倍率计费和用量统计。 -- **性能与可扩展性治理**：通过 Redis / 内存缓存、模型请求限流、流式超时与大响应缓冲、请求体上限、磁盘缓存、Pyroscope 性能采样和优雅关闭，支撑单机到多节点部署的稳定运行。 -- **组织级运营与审计层**：为团队、研究机构、企业和社区服务提供用户管理、分组管理、私有化部署、数据留存、审计和持续运营优化能力。 -- **可复用治理模板**：沉淀渠道模板、任务协议模板、价格配置、部署实践和运维经验，降低新模型、新供应商和新 Agent 场景的接入成本。 - ---- - -## 🧠 治理框架 - -MAX API 的设计把 AI 模型和 AI Agent 的运行过程纳入可配置、可观测、可核算、可审计的治理框架。 - -| 治理对象 | MAX API 提供的能力 | 目标 | -|----------|-------------------|------| -| 模型资产 | 模型列表、模型映射、模型分组、模型限制、价格规则和多模态接口管理 | 让组织知道“有哪些模型、谁能用、怎么计费、如何切换” | -| 上游渠道 | 供应商渠道、权重、分组、状态、密钥、Base URL、路径覆盖、能力矩阵、配置校验、模型发现和失败重试 | 降低单一供应商不可用、涨价、限流、误配置或接口变化带来的风险 | -| 协议格式 | OpenAI Compatible、Responses、Claude Messages、Gemini、Realtime、通用视频任务协议等协议入口和转换 | 让应用侧尽量面对稳定接口，而不是直接承担各家协议差异 | -| Agent 令牌 | API Key、令牌分组、模型范围、额度限制、过期时间和访问控制 | 为 Agent、工作流和工具调用分配独立、可回收、可限额的访问凭据 | -| 用量与成本 | 请求日志、用量统计、表达式计费、分阶段计费 JSON、任务 rate-card、预扣费和失败退款 | 把模型调用成本拆到用户、分组、令牌、模型、渠道和节点维度 | -| 异步任务 | 视频等任务提交、轮询、状态映射、结果代理和任务计费 | 统一治理长耗时、多状态、多上游格式的多模态任务 | -| 审计与安全 | 管理员侧日志审计、错误日志、请求限制、流式超时、登录与权限控制 | 在私有化部署和合规场景中提供可控的审计边界，敏感内容审计集中放在安全与限制中管理 | -| 组织运营 | 用户、分组、余额、支付、系统设置、数据看板和运维配置 | 支撑团队、研究机构、企业或社区服务的持续运营 | - ---- - -## 🧩 适用场景 - -- **组织内部 AI 模型治理平台**：统一管理用户、令牌、模型、渠道、分组、权限、价格和账单，避免每个团队重复接入和维护上游服务。 -- **Agent 应用运行与治理底座**：为 Agent、工作流和工具调用应用提供稳定的模型网关、令牌隔离、成本控制、调用观测、异常定位和审计基础。 -- **国产模型与多供应商适配中心**：持续跟踪国内外模型平台接口和价格变化，通过渠道配置、模型映射、路径覆盖和协议模板降低适配成本。 -- **多模态任务治理平台**：统一接入文本、图像、视频、音频、嵌入、重排序、实时对话等接口，并对异步任务做状态、结果代理和计费治理。 -- **模型成本与 Agent 成本核算平台**：围绕用户、令牌、模型、渠道和分组进行额度分配、费用核算、账单统计和成本分析。 -- **私有化与合规运营环境**：适合需要自主管理密钥、数据、权限、日志、审计和计费策略的团队或机构。 - ---- - -## 🚀 快速开始 - -默认使用 SQLite，本地体验无需额外数据库。 - -> [!WARNING] -> SQLite 仅适合本地体验、开发和小规模测试。正式/生产环境不建议使用 SQLite：在并发请求、多实例部署、大量日志与用量数据、数据库迁移、备份恢复或长事务场景下，可能出现锁等待、写入阻塞、迁移耗时或失败，以及可用性和数据维护问题。正式环境请使用 MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6，并配置可靠的备份与恢复方案。 - -```bash -# 1. 拉取镜像 -docker pull cscitechtop/max-api:latest - -# 2. 启动服务，数据持久化到当前目录 ./data -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest - -# 3. 访问控制台 -# 浏览器打开 http://localhost:3000 -``` - -生产部署建议使用 Docker Compose，并显式配置数据库、Redis、会话密钥、加密密钥和日志目录。 - -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API - -# 按需修改 docker-compose.yml 中的数据库、Redis 密码和环境变量 -docker compose up -d -``` - -> [!WARNING] -> 将本项目作为面向公众的生成式 AI 服务或 API 服务运营时，应先完成上游授权、备案、内容安全、实名、日志留存、税务、支付和用户协议等合规事项。 - ---- - -## ✨ 核心能力 - -### AI 模型治理 - -| 能力 | 说明 | -|------|------| -| 统一模型入口 | 支持 OpenAI 兼容接口、Responses、Claude Messages、Gemini、Realtime 等多种协议入口，应用侧可通过统一网关访问模型 | -| 多供应商模型池 | 海外可接入 OpenAI、Azure、Claude、Gemini、AWS Bedrock、Vertex AI、Ollama；国产方向持续跟踪并内置 DeepSeek、通义千问、智谱 GLM、Kimi、豆包、腾讯混元、文心、讯飞星火、MiniMax、零一万物、硅基流动等渠道适配 | -| 上游生态适配 | 支持 Codex、Dify、RAGFlow、Kling、Seedance 等应用、Agent 和多模态平台相关接口的接入治理，便于把模型调用、工作流调用和异步任务纳入统一网关 | -| 模型映射与访问范围 | 支持按渠道配置模型列表、模型映射、用户分组、令牌分组和模型限制，让不同团队、应用或 Agent 使用不同模型集合 | -| 渠道能力矩阵 | 渠道编辑界面展示 `chat/completions`、`responses`、`Claude Messages`、`Gemini native`、`embeddings`、`images`、`audio`、`rerank`、`video tasks`、`model discovery` 等能力状态，减少管理员对渠道能力的猜测 | -| 渠道配置校验 | 在保存前检查 API Key、模型列表、Base URL、额外配置、JSON 对象、Vertex AI 区域、Codex 凭证、模型发现能力和视频任务路径占位符等常见问题 | -| 多模态模型治理 | 支持聊天、图像、视频、音频、嵌入、重排序、实时对话等场景，并对视频等异步任务提供提交、轮询、状态映射和结果代理 | -| 通用视频任务协议 | 支持将不同视频上游的任务提交、查询、进度、状态映射、错误消息和结果 URL 路径统一配置到渠道中；请求体透传和改写复用渠道设置，默认路径为 `/v1/videos/create` 与 `/v1/videos/{task_id}` | -| 协议转换与自定义上游 | 支持 OpenAI Compatible、Responses、Chat Completions、Claude Messages、Gemini 等格式之间的转换与适配，也支持配置合法授权的上游地址、路径覆盖和任务协议解析规则 | - -### AI Agent 治理 / AgentOps - -| 能力 | 说明 | -|------|------| -| Agent 令牌隔离 | 可为 Agent、工作流、插件、工具调用或用户创建独立 API Key，并配置模型范围、额度、过期时间和分组 | -| 模型访问控制 | 通过用户、令牌、分组、模型限制和渠道策略控制 Agent 能调用哪些模型、走哪些渠道、消耗多少额度 | -| 调用链路观测 | 提供请求日志、用量统计、渠道命中、耗时、错误和重试信息，帮助定位 Agent 调用失败、成本异常和上游波动 | -| 成本归因 | 支持按模型、渠道、用户、分组、令牌和节点维度统计成本与用量，方便核算不同 Agent、业务线或部署节点成本 | -| 管理员审计 | 私有部署场景可按合规要求启用管理员侧日志审计能力，普通用户日志接口会过滤管理员专用审计字段 | -| 运营看板 | 提供面向管理员的统计分析、用户管理、渠道管理、系统设置和运维分析能力 | - -### 成本、计费与可靠性治理 - -**模型价格表达式** - -- **一行表达式 = 一个 token 模型的完整计价规则**：阶梯定价、缓存命中、图像 / 音频 token 分项、分时折扣、按请求头或参数动态加价，全部写在同一行，适合维护复杂模型价格。 -- **价格即真实价格**：系数直接填写「美元 / 百万 token」，`p * 2.5` 就是输入每百万 token 2.5 美元，适合按上游价格表维护成本；传统倍率模式仍保持兼容。 -- **可视化 + 原始双模式编辑**：既可逐项填价格、按档位设条件，也可直接编辑表达式，并内置常见模型预设模板。 -- **统一 JSON 批量维护**：支持在一个 `Tiered billing JSON` 窗口中维护多个模型的分阶段计费规则，保存时原子更新 `billing_mode` 与 `billing_expr`，避免手动维护多个配置项时出现不同步。 -- **自动 token 归一**：按上游格式（OpenAI / Claude）和表达式实际用到的变量，自动从输入/输出中剥离缓存、图像、音频等子类别，避免重复计费；日志中可还原命中的计价档位与明细。 - -**任务计费、传统计费与可靠性** - -- 支持视频等异步任务的参数化 rate-card 计费，按模型、供应商、时长、质量、音频、视频输入等字段匹配单价；可通过 `task_billing_setting.rate_cards` 的 JSON 窗口统一维护，并用 `vendor` 字段区分 Sora、Veo、Seedance、Kling 等供应商分区。 -- 兼容按量、按次、缓存命中等计费模式，以及模型倍率、分组倍率、渠道倍率。 -- 支持预扣费、失败退款、异常处理和消费日志，适合长耗时 Agent 调用链路和异步多模态任务。 -- 支持渠道加权随机、失败重试、禁用渠道绕过和模型级路由，降低上游异常对应用和 Agent 的影响。 -- 支持 Redis 缓存与内存缓存，适配单机和多机部署。 - -### 性能与可扩展性治理 - -| 能力 | 说明 | -|------|------| -| 缓存与多节点扩展 | 单机可使用内存缓存，多机可接入 Redis；用户、令牌、渠道亲和、额度相关缓存减少重复数据库访问，并通过 `SESSION_SECRET`、`CRYPTO_SECRET`、`NODE_NAME` 保持会话、加密和日志归属一致 | -| 请求限流与容量保护 | 支持全局 API / Web 限流、关键接口限流、搜索限流、模型请求限流和按分组配置的模型请求配额；可使用 Redis 或内存计数器 | -| 流式与大请求控制 | 支持 `STREAMING_TIMEOUT`、`STREAM_SCANNER_MAX_BUFFER_MB`、`MAX_REQUEST_BODY_MB`、`MAX_FILE_DOWNLOAD_MB` 等配置，控制长流式响应、大行 SSE、解压后请求体和远程文件下载大小 | -| 中继连接调优 | 支持 `RELAY_TIMEOUT`、`RELAY_IDLE_CONN_TIMEOUT`、`RELAY_MAX_IDLE_CONNS`、`RELAY_MAX_IDLE_CONNS_PER_HOST` 配置上游 HTTP 连接池与超时策略 | -| 磁盘缓存与性能观测 | 系统性能设置可启用大请求体磁盘缓存、配置缓存阈值和容量；运维接口可查看 / 清理磁盘缓存，并可通过 Pyroscope 采集 CPU、内存、goroutine、mutex 和 block profile | -| 平滑退出与数据落盘 | 关闭进程时支持 `SHUTDOWN_TIMEOUT_SECONDS` 和 `QUOTA_DATA_CACHE_SAVE_TIMEOUT_SECONDS`，尽量在退出前完成 HTTP 关闭和额度缓存保存 | - -### 安全与组织管理 - -- 支持 JWT、WebAuthn/Passkeys、OAuth、OIDC、Telegram、Discord、LinuxDO 等登录方式。 -- 支持管理员、普通用户、分组、令牌和模型访问控制。 -- 支持请求体大小限制、流式超时控制、错误日志和运行状态检查。 -- 支持多机部署下的统一会话密钥、加密密钥和 Redis 共享缓存。 - ---- - -## 🆚 为什么使用网关 - -| 维度 | 直连各家官方 SDK / API | 通过 MAX API 网关 | -|------|------------------------|-------------------| -| 模型接入 | 每家一套 SDK、鉴权和参数 | 统一模型入口，一次接入，多模型复用 | -| 模型治理 | 模型清单、价格、权限和渠道分散在各平台 | 统一管理模型、渠道、映射、分组、额度和价格规则 | -| Agent 访问 | Agent 直接持有上游 Key，难以回收和限额 | 为 Agent 分配独立令牌，并限制模型、额度、过期时间和分组 | -| 协议差异 | 应用自行适配 Claude、Gemini、Responses 等格式 | 网关统一做协议转换和供应商适配 | -| 失败处理 | 应用自行实现重试、降级和错误归一 | 渠道失败自动重试、加权路由和错误处理 | -| 性能与扩展 | 应用自行处理超时、限流、连接池和缓存 | 网关集中提供流式超时、请求限制、Redis / 内存缓存、连接池调优和性能观测 | -| 成本统计 | 各平台账单分散，难以按用户或 Agent 核算 | 统一额度、计费、用量统计和消费日志，可按令牌和模型归因 | -| 审计边界 | 应用侧分散记录，权限和留存策略不统一 | 管理员侧统一审计入口，普通用户日志过滤管理员专用字段 | -| 私有化 | 密钥、日志和计费策略分散 | 自托管，自主掌控密钥、数据、日志和策略 | - ---- - -## 🧭 架构概览 - -MAX API 采用分层架构：应用、SDK 或 Agent 请求经统一入口进入，依次经过路由、中间件、控制器和业务服务层，最终由中继层适配到对应上游供应商；数据层和缓存层为模型治理、Agent 令牌治理、计费、日志、审计和任务状态提供持久化与加速能力。 - -![MAX API 系统架构图](./docs/images/MAX-API架构图.png) - -以下简图展示核心请求链路： - -```mermaid -flowchart LR - Client[客户端 / SDK / Agent] --> Router[Router
路由] - Router --> MW[Middleware
鉴权 · 限流 · 分发 · 日志] - MW --> Ctrl[Controller
请求处理器] - Ctrl --> Svc[Service
模型治理 · AgentOps · 计费审计] - Svc --> Relay[Relay
中继 / 协议转换] - Relay --> Adapters[Channel 适配器
OpenAI · Claude · Gemini · 国产平台 · 自定义上游] - Adapters --> Upstream[(上游模型服务)] - Svc --> Model[Model
GORM] - Model --> DB[(SQLite · MySQL · PostgreSQL)] - Svc --> Cache[(Redis · 内存缓存)] -``` - -### 目录结构 - -| 目录 | 职责 | -|------|------| -| `router/` | HTTP 路由，包含 API、relay、dashboard 和 web 入口 | -| `controller/` | 请求处理器，负责参数解析、鉴权后的业务入口和响应封装 | -| `service/` | 业务逻辑，包含模型治理、AgentOps、日志、计费、审计、任务、渠道和系统配置等能力 | -| `model/` | 数据模型与数据库访问，基于 GORM 兼容 SQLite、MySQL、PostgreSQL | -| `relay/` | AI API 中继、协议转换和供应商适配 | -| `relay/channel/` | 各供应商适配器，如 openai、claude、gemini、aws 等 | -| `middleware/` | 鉴权、限流、CORS、日志、请求分发和上下文处理 | -| `setting/` | 模型价格、任务计费、运营、系统、安全和性能配置 | -| `common/` | JSON、加密、Redis、限流、环境变量等共享工具 | -| `dto/` / `types/` | 请求、响应、错误和中继格式类型定义 | -| `constant/` | API 类型、渠道类型、上下文键等常量 | -| `i18n/` / `oauth/` / `pkg/` | 后端国际化、OAuth 实现和内部包 | -| `web/` | 前端主题容器，默认主题位于 `web/default/` | - -### 技术栈 - -| 层 | 技术 | -|------|------| -| 后端 | Go 1.25+、Gin、GORM v2 | -| 前端 | React 19、TypeScript、Rsbuild、Base UI、Tailwind CSS | -| 包管理 | Bun workspace | -| 数据库 | SQLite / MySQL ≥ 5.7.8 / PostgreSQL ≥ 9.6 | -| 缓存 | Redis + 内存缓存 | -| 鉴权 | JWT、WebAuthn/Passkeys、OAuth、OIDC | - ---- - -## 🤖 AI 模型与接口支持 +

+ QQ 群：950126533 • + 微信群：搜索 MAX-API +

-> 实际可用模型取决于你的上游授权、渠道配置、模型映射和服务商支持情况。MAX API 的重点是把这些模型能力纳入统一治理，而不是提供上游模型服务本身。 +| 社区入口 | 用途 | +|---|---| +| [MAX-API-Next GitHub](https://github.com/MAX-API-Next) | 关注社区项目、技术方向与开放协作 | +| [MAX API Issues](https://github.com/MAX-API-Next/MAX-API/issues) | 提交可复现问题、需求建议和兼容性变化 | +| [MAX API Releases](https://github.com/MAX-API-Next/MAX-API/releases) | 获取正式版与 Preview 版本动态 | +| [Ask DeepWiki](https://deepwiki.com/MAX-API-Next/MAX-API) | 快速检索和理解项目代码 | +| 技术与生态合作 | 联系 `maxapi@max-api.ai` | -| 类型 | 说明 | -|------|------| -| OpenAI-Compatible | Chat Completions、Embeddings、Images、Audio 等兼容接口，可作为多数应用和 Agent 的通用模型入口 | -| OpenAI Responses | Responses 格式请求、中继与 Responses ↔ Chat Completions 兼容转换，适合逐步接入新的 OpenAI 应用协议 | -| Claude Messages | Claude Messages 格式与 OpenAI 兼容格式转换，降低应用侧多协议维护成本 | -| Google Gemini | Gemini 聊天、文本，以及 `/v1/responses` 兼容转换能力 | -| Azure OpenAI | Azure OpenAI 与 Realtime 相关接口 | -| AWS Bedrock | Bedrock Runtime 相关模型接入 | -| 上游平台和应用生态 | AWS、Azure、Vertex、Ollama、Codex、Dify、RAGFlow、Kling、Seedance 等平台或应用形态可按渠道能力接入治理 | -| 国产模型与平台 | 内置 DeepSeek、通义千问 / 阿里云百炼、智谱 GLM、Kimi、豆包 / 火山引擎、腾讯混元、百度文心 / 千帆、讯飞星火、MiniMax、零一万物、硅基流动等适配器或兼容接入能力 | -| `rerank` | Cohere、Jina 等重排序模型，可用于检索增强和 Agent 检索链路 | -| Midjourney / Suno / Dify | 图像、音乐、工作流等服务适配 | -| 视频任务接口 | 支持 `/v1/videos/create`、`/v1/videos/{task_id}` 等视频生成任务的提交、请求体透传或参数覆盖、轮询、状态映射、结果代理和参数化任务计费 | -| 自定义上游 | 支持配置合法授权的上游接口地址、协议适配规则、Responses / Chat 转换、路径覆盖、状态映射、错误消息路径和任务结果解析 | +### 我们正在寻找这些共建者 -### 支持的主要接口 +- **模型与协议贡献者**：适配新模型、新供应商、Reasoning、工具调用和多模态任务协议。 +- **Agent 与应用开发者**：分享 Dify、RAGFlow、Codex、MCP、工作流和研究 Agent 的接入与治理实践。 +- **可靠性与安全工程师**：完善跨数据库测试、异步任务恢复、结算安全、缓存一致性和权限边界。 +- **文档与社区贡献者**：改进部署教程、FAQ、案例、翻译、可复现实验和新贡献者指引。 +- **研究者与评测开发者**：共建 Evidence、Evaluator、Detector、Runbook 和受控自治方案。
-查看接口类别 - -- 聊天接口：`/v1/chat/completions` -- 响应接口：`/v1/responses` -- 图像接口：`/v1/images/*` -- 音频接口：`/v1/audio/*` -- 视频接口：`/v1/videos/*` -- 嵌入接口：`/v1/embeddings` -- 重排序接口：`/v1/rerank` -- 实时对话：OpenAI Realtime 兼容接口 -- Claude Messages：Claude 原生格式入口 -- Gemini：Google Gemini 格式入口 - -
- -### Reasoning Effort 支持 - -
-查看示例模型命名 - -**OpenAI 系列：** - -- `o3-mini-high` -- `o3-mini-medium` -- `o3-mini-low` -- `gpt-5-high` -- `gpt-5-medium` -- `gpt-5-low` +查看共建方向、协作原则与参与方式 -**Claude 思考模型：** +| 共建方向 | 适合的贡献 | +|---|---| +| 模型与供应商生态 | 模型/协议适配、兼容测试、模型列表与弃用变化、渠道配置模板 | +| AgentOps 与 AGI 应用治理 | Agent 接入示例、令牌与权限边界、成本治理和运行实践 | +| SmartOps 与 Evidence | 脱敏故障样本、指标口径、告警规则、数据质量说明、诊断与评测方法 | +| 可靠性、计费与安全 | 幂等结算、异步任务恢复、跨数据库回归、缓存一致性和高风险操作验证 | +| 文档、教程与国际化 | 部署教程、架构说明、FAQ、案例、翻译和新贡献者指引 | -- `claude-3-7-sonnet-20250219-thinking` +协作时请尽量提供最小复现、版本、环境、脱敏日志或测试证据；协议、数据库和用户契约变更需要说明兼容性、迁移与回滚路径。请勿提交真实 API Key、客户数据、支付原始记录、私有日志或未经授权的数据。涉及资金、安全、密钥、生产数据或自动执行的贡献，需要更严格的测试、独立审查和明确责任人。 -**Gemini 系列：** +你可以从以下方式开始： -- `gemini-2.5-flash-thinking` -- `gemini-2.5-flash-nothinking` -- `gemini-2.5-pro-thinking` -- `gemini-2.5-pro-thinking-128` -- 也可以在 Gemini 模型名后追加 `-low`、`-medium`、`-high` 来控制思考力度。 +1. 提交一个可复现的问题、协议差异或模型兼容性变化。 +2. 为已有问题补充失败测试、跨数据库用例、前端回归或脱敏 Evidence。 +3. 完善模型/渠道配置、部署说明、FAQ、架构文档或多语言翻译。 +4. 分享经过脱敏的 Agent 接入、成本治理、SmartOps 和私有化部署实践。 +5. 提交 Evaluator、Detector、Runbook 或受控自治设计提案，并明确能力边界与风险。
---- - -## 🔧 治理配置 - -### 初始治理配置建议 - -1. 部署完成后进入控制台，创建或确认管理员账号。 -2. 配置系统设置、用户注册策略、登录方式和安全限制。 -3. 添加上游渠道，填写合法授权的 API Key、Base URL、模型列表、模型映射和渠道设置。 -4. 根据组织结构配置用户分组、令牌分组、模型限制、额度策略和价格规则，将模型能力纳入访问控制。 -5. 为应用、Agent 或工作流创建独立令牌，按业务线、环境或风险级别配置模型范围和额度。 -6. 在运营设置中配置失败重试、日志记录、缓存策略和消费统计。 -7. 如需管理员侧内容审计，应在合规前提下进入“系统设置 → 安全与限制 → 日志审计”启用，并确保“记录配额使用量（日志维护）”已开启。 - -### 渠道能力矩阵与配置校验 - -渠道新建或编辑时，系统会根据渠道类型展示能力矩阵，并给出实时配置校验结果。矩阵中的接口名称保留原始技术表述，例如 `chat/completions`、`responses`、`embeddings`、`rerank`、`video tasks`，说明文字使用中文，便于管理员判断当前渠道能承担哪些模型和任务。 - -配置校验覆盖以下常见问题： - -- 新建渠道缺少 API Key、模型列表为空、需要 Base URL 或额外配置但未填写。 -- Base URL 误填到 `/v1` 结尾，导致系统再次拼接上游路径。 -- `setting`、`param_override`、`header_override`、`settings` 等字段不是 JSON 对象。 -- Vertex AI 区域配置缺少 `default`，或服务账号密钥不是有效 JSON。 -- Codex 渠道凭证缺少 `access_token` 或 `account_id`。 -- 当前渠道不支持模型发现，但开启了上游模型检查或自动同步。 -- 视频任务查询路径缺少 `{task_id}`、`{operation_name}` 或 `{upstream_task_id}` 占位符。 - -### 通用视频任务协议 - -视频模型供应商的接口经常在路径、任务 ID、状态字段、进度字段、错误字段和结果 URL 字段上不一致。MAX API 将原先面向单一模型的任务协议能力扩展为通用视频任务协议，适用于 OpenAI、Ali、Gemini、MiniMax、Vertex AI、VolcEngine、Kling、Jimeng、Vidu、Doubao Video、Sora 等视频任务渠道。 - -支持的配置层级： - -- **仅路径覆盖**：只配置 `submit_path` 和 `query_path`，系统仍使用对应渠道的官方响应解析逻辑，适合只改上游路径的兼容渠道。 -- **完整协议解析**：设置 `task_protocol = "generic_video_task"`，同时配置任务 ID、状态、进度、结果 URL、错误消息和状态映射路径，适合非标准视频任务响应。 -- **请求体处理**：通用视频任务协议不再单独定义请求体生成模式。需要原样透传客户端 JSON 时使用渠道设置里的 `Pass Through Body`；需要字段改写、默认值或 header 联动时使用已有的 `Param Override`。 - -默认任务路径： - -```json -{ - "task_protocol": "generic_video_task", - "task_protocol_config": { - "submit_path": "/v1/videos/create", - "query_path": "/v1/videos/{task_id}", - "task_id_path": "task_id", - "status_path": "status", - "progress_path": "progress", - "result_url_paths": [ - "result.primary_url", - "result.urls.0", - "data.result.primary_url", - "url", - "video_url", - "download_url" - ], - "error_message_path": "error_message", - "status_map": { - "queued": "QUEUED", - "running": "IN_PROGRESS", - "succeeded": "SUCCESS", - "failed": "FAILURE" - } - } -} -``` - -查询路径支持 `{task_id}`、`{operation_name}`、`{upstream_task_id}`。其中 `{operation_name}` 可保留多段路径值，适合 Gemini / Vertex 风格的 operation 查询接口。视频内容可通过 `/v1/videos/{task_id}/content` 代理读取；在需要隐藏上游资源域名的部署中，建议让终端用户访问该内容代理地址，并配合鉴权、SSRF 防护和允许端口配置使用。 - -### 计费 JSON 维护 - -系统设置中的模型计费支持两类 JSON 统一维护入口： - -- **分阶段计费 JSON**：通过 `Tiered billing JSON` 统一维护多个模型的 `{ enabled, expr }` 配置，保存时同步更新 `billing_mode` 与 `billing_expr`。 -- **任务 rate-card JSON**：通过 `task_billing_setting.rate_cards` 统一维护异步任务计费规则，可按 `vendor` 分区维护 Sora、Veo、Seedance、Kling 等视频模型的不同计费表。 - -Seedance 2.0 等视频模型可按分辨率、视频输入等请求参数参与倍率或 rate-card 计算；使用透传或参数覆盖时，应确保最终提交给上游的字段与计费字段保持一致。 - -示例结构： - -```json -{ - "model-name": { - "enabled": true, - "expr": "len <= 200000 ? tier(\"standard\", p * 3 + c * 15) : tier(\"long_context\", p * 6 + c * 22.5)" - } -} -``` +配套文档：[MAX-API-Docs](https://github.com/MAX-API-Next/MAX-API-Docs)（部署、配置与使用说明）。 -任务 rate-card 可按请求参数匹配价格： - -```json -{ - "vendor/model-name": { - "vendor": "kling", - "unit": "second", - "quantity_field": "duration", - "default_quantity": 5, - "strict": true, - "defaults": { - "quality": "std", - "has_audio": "false" - }, - "rows": [ - { - "id": "std_no_audio", - "match": { - "quality": "std", - "has_audio": "false" - }, - "unit_price": 0.6 - } - ] - } -} -``` +欢迎模型厂商、Agent/工作流项目、开源社区、研究者和企业工程团队开展技术共建。正式合作、联合发布或机构名义使用应经过双方明确授权。 -### 常见运维入口 +> [!IMPORTANT] +> 面向公众提供生成式人工智能服务时，使用者应自行完成所在司法辖区要求的上游授权、备案许可、内容安全、实名、日志留存、税务、支付和用户协议等合规义务。日志审计和内容留存仅应在具备合法依据、明确告知、权限隔离和数据安全措施的场景下启用。 -| 功能 | 说明 | -|------|------| -| 渠道管理 | 配置上游供应商、模型映射、渠道权重、密钥、协议路径和状态，并通过能力矩阵与配置校验提前发现风险 | -| 模型与价格 | 维护模型列表、模型价格、表达式计费、分阶段计费 JSON、任务 rate-card JSON 和模型展示信息 | -| 令牌管理 | 为应用、Agent、工作流、工具调用或用户创建访问令牌并限制模型与额度 | -| 用户管理 | 管理用户、分组、余额、权限和状态 | -| 使用日志 | 查看调用记录、消耗、耗时、错误、渠道命中和管理员可见的审计信息 | -| 系统设置 | 管理安全限制、日志审计、模型定价、任务计费、运营策略、日志维护、支付和站点配置 | -| 数据看板 | 查看整体请求量、模型用量、消费趋势、渠道状态和 Agent 令牌成本 | +image ---- +## 🧠 面向 AGI 的技术方向 -## 🚢 部署 +AGI 应用不会长期依赖单一模型、单一协议或一次性请求。它们需要跨模型推理、工具调用、多模态任务、长期运行、成本约束、生产证据和可恢复的失败处理。MAX API 选择从这些可验证的工程问题出发，建设 AI Models and Agents governance 基础。 -### 部署要求 +| 技术方向 | 当前基础 | 对 AGI 应用的价值 | +|---|---|---| +| 多模型与多协议接入 | OpenAI Compatible、Responses、Claude Messages、Gemini、Realtime、多模态与异步任务协议 | 让应用和 Agent 面对相对稳定的入口，并能随模型生态变化持续迁移 | +| 推理与工具上下文兼容 | Reasoning Effort、工具定义、Tool Call、工具响应关联和多轮上下文转换 | 减少跨供应商切换时推理信息与工具调用语义丢失 | +| 治理控制平面 | 用户、令牌、模型范围、分组、路由、限流、额度、价格和管理员权限 | 为不同 Agent、环境和任务建立独立身份、访问边界与预算边界 | +| 可恢复计费与任务生命周期 | 预扣、最终结算、幂等记录、失败退款、异步任务轮询和人工对账状态 | 避免长任务、重试和异常窗口造成重复扣费、错误退款或不可追溯结果 | +| Evidence 与智能运维 | 日志、错误、重试、性能桶、活动告警、渠道/模型性能和结算证据 | 让诊断、评测和未来 Agent 建议建立在可追溯事实上，而不是仅依赖提示词推断 | +| 安全与组织治理 | Passkey、2FA、分作用域重新验证、会话撤销、审计和敏感操作限流 | 为高风险配置、凭据和运营操作保留明确的责任边界 | +| 受控自治与工程进化 | **长期蓝图**：Policy、Budget、Approval、Shadow、Canary、Rollback、隔离 Coding Workspace | 让自动化能力先被评测、约束和审计，再逐步进入低风险生产动作 | -| 组件 | 要求 | -|------|------| -| 容器引擎 | Docker / Docker Compose | -| 本地数据库 | SQLite，仅用于本地体验、开发或小规模测试；Docker 部署时需挂载 `/data` | -| 正式环境数据库 | MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6，并配置可靠的备份与恢复方案 | -| 缓存 | 单机可使用内存缓存，多机部署建议使用 Redis | -| 前端构建 | 使用 Bun workspace，需保留 `web/package.json` 与 `web/bun.lock` | -| 源码构建 | 使用仓库 `go.mod` 声明的 Go 版本（当前 Go 1.25.1+）和 `go.sum`；依赖或安全更新后运行 `go mod download`、`go mod verify` 并重新构建 | +### 技术原则 -### 推荐环境变量 +- **Evidence before Action**：先建立可验证事实，再进行诊断、建议或自动动作。 +- **Governance before Autonomy**：身份、权限、预算、审批、审计和回滚必须先于自治能力。 +- **One Billing Truth**：生产计费、额度与结算保持单一事实来源，不为 Agent 或插件建立第二套账务逻辑。 +- **Compatibility by Design**：持续支持 SQLite、MySQL、PostgreSQL、多供应商协议和可迁移的应用侧契约。 +- **Open Collaboration, Safe Boundaries**：开放协议适配、测试、文档、评测和治理方案，高风险生产、资金、密钥与发布动作继续由明确责任人审批。 -
-查看常用环境变量 - -| 变量名 | 说明 | 默认值 | -|--------|------|--------| -| `SESSION_SECRET` | 会话密钥，多机部署必须设置 | - | -| `CRYPTO_SECRET` | 加密密钥，使用 Redis 或多机部署时必须设置 | - | -| `SQL_DSN` | 数据库连接字符串 | - | -| `REDIS_CONN_STRING` | Redis 连接字符串 | - | -| `STREAMING_TIMEOUT` | 流式响应超时时间，单位秒 | `300` | -| `STREAM_SCANNER_MAX_BUFFER_MB` | 流式扫描器单行最大缓冲，图像 base64 等大响应可适当调大 | `64` | -| `MAX_REQUEST_BODY_MB` | 请求体最大大小，按解压后大小计算，超出返回 `413` | `32` | -| `AZURE_DEFAULT_API_VERSION` | Azure API 默认版本 | `2025-04-01-preview` | -| `ERROR_LOG_ENABLED` | 错误日志开关 | `false` | -| `NODE_NAME` | 节点名称，多机部署时用于日志定位和异步任务结算归属 | - | -| `PYROSCOPE_URL` | Pyroscope 服务地址 | - | -| `PYROSCOPE_APP_NAME` | Pyroscope 应用名 | `max-api` | -| `PYROSCOPE_BASIC_AUTH_USER` | Pyroscope Basic Auth 用户名 | - | -| `PYROSCOPE_BASIC_AUTH_PASSWORD` | Pyroscope Basic Auth 密码 | - | -| `PYROSCOPE_MUTEX_RATE` | Pyroscope mutex 采样率 | `5` | -| `PYROSCOPE_BLOCK_RATE` | Pyroscope block 采样率 | `5` | -| `HOSTNAME` | Pyroscope 标签中的主机名 | `max-api` | +### MAX API 2.0 技术亮点 -
+- **Evidence-driven SmartOps**：把资源告警、渠道/模型性能、数据质量状态和计费结算证据汇聚到统一运维入口，并保留人工审阅与真实财务状态之间的边界。 +- **面向先进模型协议持续演进**：增强 Responses、Claude Messages、Gemini 与 Ollama 的 Reasoning、缓存键、惩罚参数、工具定义和多轮 Tool Context 兼容。 +- **可恢复的计费与异步任务语义**：通过幂等 settlement、持久化 effect、任务 ID 和明确的 pending/manual 状态，避免异常重试导致重复扣费、错误退款或任务丢失。 +- **高风险操作分作用域重新验证**：Passkey、2FA、Telegram、API Token 与会话撤销采用 scope-bound step-up verification，并通过 `session_generation` 及时撤销旧会话。 +- **跨数据库与持续验证**：核心数据路径兼容 SQLite、MySQL 和 PostgreSQL；Go 测试、前端 Bun 测试、TypeScript 类型检查、JSON 包装规则和测试镜像同步共同构成发布门禁。 -### Docker Compose +## 💡 为什么需要 MAX API -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API +| 维度 | 直接连接多个供应商 | 使用 MAX API | +|---|---|---| +| 应用接入 | 分别维护 SDK、协议、鉴权和错误格式 | 应用侧使用相对稳定的统一入口 | +| 模型切换 | 修改代码、密钥和部署配置 | 通过渠道、模型映射、分组和路由调整 | +| 可用性 | 每个应用自行处理重试和上游故障 | 集中配置权重、优先级、失败重试和切换 | +| 权限与密钥 | 凭据散落在应用和环境变量中 | 集中管理令牌、模型范围、额度和有效期 | +| 成本核算 | 多家账单分散，难以归因 | 按用户、令牌、模型、渠道和分组统计 | +| 故障排查 | 日志分散，跨供应商定位困难 | 在网关侧统一观察请求、错误、重试和耗时 | -# 修改 docker-compose.yml： -# - 更换 PostgreSQL / MySQL / Redis 默认密码 -# - 按需设置 SESSION_SECRET、CRYPTO_SECRET、NODE_NAME -# - 生产环境建议配置反向代理与 HTTPS -docker compose up -d -``` +一句话概括：**供应商负责提供模型，Agent 框架负责编排业务，MAX API 负责统一接入并守住治理边界。** -### Docker 命令 +## 🚀 快速开始 -**SQLite：** +本地体验默认使用 SQLite，只需 Docker： ```bash -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest -``` +MAX_API_IMAGE=cscitechtop/max-api:latest@sha256:006d5d86887a261baab4d71ec3797d429e3771a4836e5899734aee0e7f66f2ab -**MySQL：** +docker pull "$MAX_API_IMAGE" -```bash -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e SQL_DSN="root:123456@tcp(mysql:3306)/max-api" \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest +docker run --name max-api -d --restart always -p 127.0.0.1:3000:3000 -e TZ=Asia/Shanghai -v ./data:/data "$MAX_API_IMAGE" ``` -### 从源码构建镜像 +启动后访问： -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API -docker build -t cscitechtop/max-api:latest . -``` +接下来完成三件事： -> [!NOTE] -> `Dockerfile` 会在镜像构建中下载 Go 模块。宿主机直接构建或依赖 / 安全更新后，请保持 `go.mod` 与 `go.sum` 成对提交，先运行 `go mod download && go mod verify`，再重新构建二进制或镜像；需要刷新基础镜像时可使用 `docker build --pull --no-cache -t cscitechtop/max-api:latest .`。 +1. 创建或确认管理员账号。 +2. 添加一个具有合法授权的上游渠道和 API Key。 +3. 创建访问令牌，把应用中的 Base URL 指向 MAX API。 > [!TIP] -> 前端使用 Bun workspace。构建上下文中必须保留 `web/package.json`、`web/bun.lock` 和 `web/default/package.json`，否则 `catalog:` 依赖无法解析。 - -### 多机部署注意事项 - +> 生产环境建议使用正式版。Preview 版本用于测试和灰度验证，升级前请备份数据库并准备回滚方案。 +> > [!WARNING] -> - 必须设置相同的 `SESSION_SECRET`，否则不同节点之间登录状态不一致。 -> - 使用共享 Redis 时必须设置相同的 `CRYPTO_SECRET`，否则加密数据无法解密。 -> - 多节点建议设置稳定的 `NODE_NAME`，便于在日志、审计信息和异步任务结算中定位来源节点。 -> - 生产环境应使用外部数据库、外部 Redis、HTTPS 反向代理和可靠的备份策略。 +> SQLite 适合本地体验、开发和小规模测试。正式环境建议使用仍在供应商安全支持周期内的 MySQL（建议 8.4 LTS）或 PostgreSQL（建议 14+），并配置 Redis、HTTPS、备份和恢复方案。项目兼容性下限仍为 MySQL ≥ 5.7.8、PostgreSQL ≥ 9.6，但不建议将其用于生产。 ---- +## ✨ 当前能力 -## 🗺️ 路线图 +以下能力已经在当前系统中提供： -以下为方向性规划，会根据维护节奏、真实场景和社区需求调整，不构成时间承诺。 +| 能力 | 主要用途 | +|---|---| +| 统一模型入口 | 接入 OpenAI Compatible、Responses、Claude Messages、Gemini、Realtime 和多模态任务接口 | +| 多供应商路由 | 管理渠道、权重、优先级、分组、模型映射、失败重试和跨供应商切换 | +| 身份与访问控制 | 管理用户、令牌、模型范围、分组、额度、有效期、限流和管理员权限 | +| 成本与计费 | 支持倍率、固定价格、表达式计费、异步任务 rate-card、预扣费、结算和失败退款 | +| 日志与审计 | 按用户、令牌、模型、渠道、分组和节点查看使用、错误、重试和管理操作 | +| 智能运维中心 | 集中查看活动告警、渠道性能、模型性能、系统信息和计费结算对账证据，辅助管理员发现、定位和审阅生产问题 | +| 私有化部署 | 支持 SQLite、MySQL、PostgreSQL、Redis、多节点和独立日志库 | +| 上游扩展 | 支持协议适配、路径覆盖、参数/Header 覆盖、模型发现和任务状态映射 | -- **模型治理深化**：围绕模型目录、模型价格、模型权限、模型映射、模型能力标签和供应商变更，持续增强治理能力。 -- **AgentOps 深化**：围绕 Agent、工具调用、工作流和 MCP 风格工具 / 服务接入，持续优化调用链路、成本归因、异常定位和治理能力。 -- **多模态任务治理**：增强图像、视频、音频和实时交互任务的计费、限流、状态追踪和结果代理。 -- **协议转换增强**：持续完善 OpenAI Compatible、Responses、Claude Messages、Gemini 等协议之间的转换。 -- **国产模型与平台跟踪适配**：跟进国产模型、云平台、价格规则和 API 协议变化，沉淀可复用的渠道、价格和任务协议配置。 -- **供应商适配模板化**：让路径覆盖、任务协议、状态映射、错误解析和结果解析更容易配置和复用。 -- **治理审计与运营优化**：完善请求链路、成本追踪、错误分析、管理员审计、日志留存和运维报表。 -- **组织级运营能力**：增强多租户、分组、账单、权限、风控和私有化部署体验。 +### 适用场景 -欢迎在 [GitHub Issues](https://github.com/MAX-API-Next/MAX-API/issues) 提出需求、问题和改进建议。 +- **团队或组织内部模型网关**：统一管理用户、令牌、模型、供应商、权限和费用。 +- **AI 应用与 Agent 运行底座**：为应用、Agent 和工作流提供模型访问控制、成本归因与异常定位。 +- **多供应商容灾与迁移**：通过模型映射、加权路由、失败重试和灰度切换降低单一上游风险。 +- **多模态任务治理**：统一管理图像、音频、视频、嵌入、重排序和实时对话接口。 +- **私有化与合规运营**：自主管理密钥、数据、日志、审计、价格和部署环境。 ---- +## 🩺 智能运维中心 -## ❓ 常见问题 +**智能运维中心是 MAX API 2.0 的重大更新，也是项目从统一模型网关走向 AGI 原生治理与运营基础设施的关键一步。** -
-MAX API 会提供模型服务或 API Key 吗？ +它将生产观测、资源告警、模型与渠道性能、系统信息和计费结算对账集中到统一管理员入口。当前能力强调“看见问题、保留证据、通知管理员、受控审阅”，并不是会自动修改渠道、路由、余额或主机的自治 Agent。 -不会。MAX API 是模型与 Agent 工作负载的网关治理层，不提供上游模型账号、API Key、基础模型训练能力或模型服务本身。使用者需要自行获得合法授权的上游服务。 +| 模块 | 当前提供的内容 | +|---|---| +| 活动告警 | 对当前节点的 CPU、内存和磁盘持续超阈值进行去重告警，在恢复时发送恢复通知；复用管理员已有的 Email、Webhook、Bark 或 Gotify 配置 | +| 渠道性能 | 查看请求与错误、消耗额度、估算成功率、日志延迟、重试、探测延迟和最近观测时间；详情可查看该渠道最近 24 小时的模型与分组表现 | +| 模型性能 | 汇总所有模型的渠道数、请求与错误、消耗额度、估算成功率、日志延迟、吞吐量和重试；详情提供各分组性能、延迟趋势和可用率趋势 | +| 计费结算对账 | 展示 `pending` / `manual` 正向最终结算、未结资金、重试和错误证据；根管理员可配置默认用户阻断策略，管理员可按 `id + revision` 原子批量审阅并关闭告警 | +| 系统信息 | 查看节点、运行实例和系统任务等信息；该模块继续要求超级管理员权限 | -
- -
-MAX API 和 Agent 框架是什么关系？ +活动告警页面每 5 秒读取一次当前告警状态，但不会触发新的检测或修复动作。渠道与模型列表默认查询最近 1 小时，管理员可以输入 `1–168` 小时的自定义窗口；它们不会自动反复统计大日志库，只有点击“应用筛选”或“刷新”时才执行查询，详情数据在打开时按需加载。 -MAX API 不替代 Dify、LangChain、MCP Server、工作流引擎或业务 Agent 应用。它位于这些应用与上游模型服务之间，负责模型接入、令牌隔离、成本核算、路由容灾、日志观测和管理员审计等治理能力。 - -
- -
-为什么强调 AI 模型治理？ +计费结算对账把财务恢复状态与运维告警状态严格分离：“审阅并关闭”只记录管理员审阅并关闭当前告警，不会把结算标记为 `applied`，不会修改余额、已应用差额或 effect 状态。批量审阅绑定当前财务 revision；刷新后记录发生变化时，旧选择会自动失效，避免使用过期证据作出操作。 -在真实组织中，模型不只是一个 API 名称，还涉及供应商、价格、上下文长度、协议格式、权限范围、稳定性和审计边界。MAX API 的价值在于把这些分散变量统一配置、统一观察和统一核算。 - -
- -
-支持哪些数据库？ - -支持 SQLite、MySQL ≥ 5.7.8 和 PostgreSQL ≥ 9.6。本地体验可使用 SQLite；生产环境建议使用 MySQL 或 PostgreSQL，并做好备份。 - -
- -
-能否从 New API / One API 迁移？ - -项目兼容 New API 与原版 One API 的主要数据结构，通常可以复用既有数据。迁移前仍建议备份数据库，并在测试环境验证渠道、倍率、用户、令牌和日志数据。 +> [!NOTE] +> 当前生产性能主要聚合既有 Consume/Error 日志和 `perf_metrics`：估算成功率并非完整的 Relay Attempt 成功率，吞吐量与趋势属于性能桶级近似值。日志关闭、历史数据缺失、采集关闭、窗口无样本或查询失败时，页面会显示相应的数据质量状态。 +> +> 活动告警依赖性能监控和资源阈值配置；阈值设为 `0` 时表示关闭该资源告警，需连续两个有效样本才会触发。状态与通知队列只保存在当前进程内存中：进程重启后不会保留，多节点也不会自动合并为跨节点 Incident。渠道、模型和系统观测保持只读；结算审阅仅更新审阅元数据与用户阻断策略，不执行资金结算。智能运维中心不会自动测试、禁用、调权、切换渠道或修复主机。 -
+这一阶段的价值，是先完成“看见问题、通知管理员、提供证据、受控审阅”的闭环，为后续统一 Evidence、诊断 Agent、Evaluator 和受控自动化建立基础。 -
-多机部署需要注意什么？ +## 🔌 模型、接口与扩展 -必须统一 `SESSION_SECRET`。如果使用共享 Redis，也必须统一 `CRYPTO_SECRET`。否则可能出现登录状态不一致、缓存数据无法解密或任务状态异常。 +> 实际可用能力取决于你的上游授权、渠道配置、模型映射和供应商支持。MAX API 负责治理这些能力，不提供模型服务本身。 -
+| 类别 | 接口或能力 | +|---|---| +| 通用模型接口 | Chat Completions、Responses、Embeddings、Rerank、Images、Audio、Video | +| 原生与实时协议 | Claude Messages、Google Gemini、OpenAI Realtime 等入口 | +| 推理与工具调用 | 支持 Reasoning Effort、函数工具、Tool Call ID、工具名称和多轮工具响应关联，并按不同上游能力进行协议转换 | +| 异步任务 | 任务提交、轮询、状态映射、结果代理和参数化计费 | +| 自定义上游 | Base URL、路径、参数、Header、状态字段和结果字段映射 | -
-图像生成、流式响应或大响应被截断怎么办？ +覆盖 OpenAI、Claude、Gemini、Azure、AWS Bedrock、Vertex AI、Ollama 及多种国内模型平台，也可治理 Codex、Dify、RAGFlow 和多模态任务服务。具体支持范围以当前版本和渠道类型为准。 -可调大 `STREAM_SCANNER_MAX_BUFFER_MB`。4K 图像、base64 图片、长流式响应等场景可能需要更大的扫描缓冲。 +### 系统工作方式与技术栈 -
+![MAX API 系统架构图](./docs/images/MAX-API架构图.png) -
-请求体过大返回 413 怎么办？ +```text +应用 / SDK / Agent + → 统一接口与身份鉴权 + → 模型权限、限流、预算和安全检查 + → 渠道选择、映射与失败重试 + → 上游协议适配 + → 可恢复结算、Evidence、日志和审计 + → 智能运维中心与管理员治理 +``` -调整 `MAX_REQUEST_BODY_MB`。该限制按解压后的请求体大小计算，用于防止超大请求或 zip bomb 导致内存暴涨。 +后端使用 Go、Gin 和 GORM，前端使用 React 19、TypeScript、Base UI 与 Tailwind CSS，数据层兼容 SQLite、MySQL 和 PostgreSQL，并可使用 Redis 与独立日志库。供应商协议适配位于独立 Relay/Channel 层，计费与结算集中在统一服务边界中，管理端通过 SmartOps 展示只读观测和受限治理入口。 -
+## 🛡️ 治理与运营 -
-用户能看到管理员日志审计中的输入输出内容吗？ +生产环境建议按以下顺序配置： -正常用户日志接口会过滤管理员专用字段，普通用户无法在自助使用日志中看到管理员审计内容。数据库管理员、系统管理员或拥有管理员日志接口权限的人仍可能访问相关数据，因此应按合规要求严格控制权限。 +1. 配置登录、安全限制和用户注册策略。 +2. 添加合法授权的上游渠道，确认模型、能力和协议配置。 +3. 按团队、业务或环境设置分组、令牌、模型范围、额度和价格。 +4. 为每个应用、Agent 或环境使用独立令牌，避免共享凭据和成本归属。 +5. 配置重试、日志与告警，通过数据看板和智能运维中心持续观察。 -
+渠道能力校验、表达式计费、通用任务协议、管理员审计和性能参数等高级配置，请查看 [详细文档](https://docs.max-api.ai)。 -
-为什么 Docker 构建时提示 `catalog:` 依赖无法解析？ +## 🧭 演进路线 -前端使用 Bun workspace，`catalog:` 依赖定义在 `web/package.json`。构建时不能用 `web/default/package.json` 覆盖 workspace 根 `package.json`，并且需要保留 `web/bun.lock`。 +MAX API 将继续以 **AI Models and Agents governance** 为核心，从统一网关、智能运维和可恢复结算出发，逐步建设面向 AGI 应用的 Evidence、评测、策略与受控执行能力。长期方向不是让一个无边界 Agent 接管生产系统，而是建立可验证、可审批、可停止、可回滚的工程闭环。 -
+| 阶段 | 状态 | 重点 | +|---|---|---| +| 统一网关与智能运维 | **现已提供** | 接入、鉴权、路由、计费、日志、资源告警、渠道/模型性能、系统信息和计费结算对账 | +| Evidence 事实层 | **近期建设** | 统一模型请求、系统日志、指标、Task、路由、策略、结算和审计事件，向 Agent 提供脱敏、限权、只读接口 | +| 开放评测与治理模板 | **规划中** | 与社区沉淀模型/协议兼容测试、匿名故障样本、评测集、Runbook、Detector 和行业治理模板 | +| 受控自治运维 | **长期蓝图** | 在 Policy、Budget、Approval、Shadow、Canary 和 Rollback 约束下评估低风险自动动作 | +| 受控能力进化 | **长期蓝图** | 在隔离 Coding Workspace 中生成、测试和审阅候选改进，不直接修改生产系统 | +| AGI 工程闭环 | **长期方向** | 将 Evidence、评测、治理策略、人工审批与可回滚执行连接为可验证闭环 | ---- +MAX API 不是基础模型，也不宣称当前已经实现 AGI 或自治运维。路线图中的长期能力只有在证据、权限、预算、审批和回滚边界完善后才会逐步验证。 -## 🔗 相关项目 +## 🚢 Preview 部署 -| 项目 | 说明 | -|------|------| -| [One API](https://github.com/songquanpeng/one-api) | MIT 协议 | -| [New API](https://github.com/QuantumNous/new-api) | AGPLv3 协议 | -| [Midjourney-Proxy](https://github.com/novicezk/midjourney-proxy) | Apache-2.0 协议 | -| [Suno API](https://github.com/Suno-API/Suno-API) | MIT 协议 | +以下步骤用于 Preview 版本的测试和灰度验证。生产环境请改用正式版，并沿用相同的校验和回滚流程。 -### 配套工具 +推荐使用 Docker Compose： -| 项目 | 说明 | -|------|------| -| [max-api-key-tool](https://github.com/MAX-API-Next/MAX-API-key-tool) | Key 额度查询工具 | -| [max-api-horizon](https://github.com/MAX-API-Next/MAX-API-horizon) | MAX API 高性能优化版 | +```bash +MAX_API_VERSION=v2.0.0-smartops.pre1 +MAX_API_COMMIT=b7096156549edc930ca244891afb1ba5632dbe8f +git clone --branch "$MAX_API_VERSION" --depth 1 https://github.com/MAX-API-Next/MAX-API.git +cd MAX-API ---- +actual_commit="$(git rev-parse HEAD)" +if [ "$actual_commit" != "$MAX_API_COMMIT" ]; then + echo "Unexpected commit: $actual_commit" >&2 + exit 1 +fi -## 📚 文档与支持 - -| 资源 | 链接 | -|------|------| -| 官方文档 | [MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) | -| 问题反馈 | [GitHub Issues](https://github.com/MAX-API-Next/MAX-API/issues) | -| 最新发布 | [Releases](https://github.com/MAX-API-Next/MAX-API/releases) | -| DeepWiki | [Ask DeepWiki](https://deepwiki.com/MAX-API-Next/MAX-API) | - -### 二次开发与社区鸣谢 - -如果你基于本项目进行二次开发并仅供自用，欢迎在项目主页、页脚或“关于”页面等明显位置，任选一种方式保留项目来源或社区鸣谢： - -- 添加项目地址：[MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) -- 鸣谢社区：[MAX-API-Next](https://github.com/MAX-API-Next) - -参考前端嵌入代码（React / Tailwind CSS，可按需保留其中一项）： - -```tsx -

- 基于{' '} - - MAX-API-Next/MAX-API - {' '} - 二次开发 · 感谢{' '} - - MAX-API-Next 社区 - -

+# 修改 docker-compose.yml 中的数据库、Redis 密码和密钥 +docker compose up -d ``` -满足上述任一展示要求并保持链接清晰可见，即自动获得本项目的临时商用授权，无需另行申请或等待确认。该授权为非永久授权，仅在持续满足展示要求期间有效；有效期及后续调整以项目方在本 README 或官方社区发布的最新说明为准。 +### 部署检查 -本项目基于 [One API](https://github.com/songquanpeng/one-api) 和 [New API](https://github.com/QuantumNous/new-api) 开发。现阶段，MAX API 主要在上述项目基础上持续增强 AI API 网关与治理能力、扩展功能并修复问题。商业使用本项目时，还须分别遵守 One API 的 MIT 许可证与 New API 的 AGPLv3 许可证，具体以各上游项目的 `LICENSE` 文件为准；本项目提供的临时商用授权不替代、也不免除相关上游项目的开源许可义务。 +| 组件 | 建议 | +|---|---| +| 数据库 | 使用仍在供应商安全支持周期内的 MySQL（建议 8.4 LTS）或 PostgreSQL（建议 14+），并配置备份与恢复 | +| 缓存 | 单机可使用内存缓存，多节点部署建议使用 Redis | +| 入口 | 配置 HTTPS 反向代理、请求大小限制和可信网络策略 | +| 密钥 | 显式配置随机 `SESSION_SECRET`；`CRYPTO_SECRET` 为可选覆盖项，未设置时回退到 `SESSION_SECRET`，如单独设置则需在 Redis/多节点场景统一 | +| 节点 | 每个节点设置稳定且唯一的 `NODE_NAME` | +| 日志 | 根据合规和运维需要配置 `LOG_SQL_DSN`、清理与保留策略 | -如不再满足展示要求，或临时授权到期、被公告调整或终止，仍需按 AGPLv3 或项目方另行书面授权使用本项目。如需长期商用授权，请联系：maxapi@max-api.ai。 +多节点必须统一 `SESSION_SECRET`，并为每个节点使用不同的 `NODE_NAME`。`CRYPTO_SECRET` 为可选覆盖项，未设置时使用 `SESSION_SECRET`；如显式设置，则所有节点必须使用相同值。独立日志库使用 `LOG_SQL_DSN`；错误性能统计需要按需启用 `ERROR_LOG_ENABLED`。完整环境变量和源码构建说明见 [详细文档](https://docs.max-api.ai)。 -欢迎提交 Issue、改进文档、补充供应商适配经验、完善部署方案或贡献代码。 +## 🤝 项目来源、致谢与二次开发 ---- +MAX API 基于 [One API](https://github.com/songquanpeng/one-api) 和 [New API](https://github.com/QuantumNous/new-api) 的开源成果持续开发。感谢上游项目、贡献者，以及所有参与协议适配、测试、文档、翻译与问题反馈的社区成员。 -## 📜 许可证 +根据 [NOTICE](./NOTICE) 和 AGPLv3 第 7 节，包含用户界面的修改版本必须在显著可见的“关于”、法律声明、页脚或署名位置同时保留： -本项目采用 [GNU Affero 通用公共许可证 v3.0 (AGPLv3)](./LICENSE) 授权。 +- MAX API 原项目链接：[MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) +- MAX API NOTICE 中的原文署名：`Frontend design and development by MAX API contributors.` +- New API 上游项目链接：[QuantumNous/new-api](https://github.com/QuantumNous/new-api) +- New API NOTICE 中的原文署名：`Frontend design and development by New API contributors.` +- 明确的修改声明及相关修改日期 -除默认的 AGPLv3 授权外，符合上文“二次开发与社区鸣谢”条件的自用二开项目，可按该说明自动获得非永久的临时商用授权。该临时授权仅覆盖 MAX API 项目方有权授权的新增与修改部分，并不包含或代替 One API、New API 等上游项目的许可授权。 +可以额外鸣谢 [MAX-API-Next 社区](https://github.com/MAX-API-Next)，但社区鸣谢不能替代上述必需的项目链接、原文署名和变更标记。 -如果你修改并通过网络向用户提供本项目服务，请理解并遵守 AGPLv3 对应源码提供等义务。商业合作、机构合作或其他授权问题，请联系：maxapi@max-api.ai。 +持续满足上述展示与 NOTICE 要求，即自动获得本项目的非永久临时商用授权，无需另行申请或等待确认；该授权仅覆盖 MAX API 项目方有权授权的部分，不免除 AGPLv3 或 One API、New API 等上游项目的许可义务。最新条件以正式 README 与社区公告为准。 ---- - -## 🌟 Star History +## 📜 许可证 -
+本项目采用 [GNU Affero 通用公共许可证 v3.0（AGPLv3）](./LICENSE) 授权。 -[![Star History Chart](https://api.star-history.com/svg?repos=MAX-API-Next/MAX-API&type=Date)](https://star-history.com/#MAX-API-Next/MAX-API&Date) +临时商用授权仅覆盖 MAX API 项目方有权授权的新增与修改部分，不包含、替代或免除 One API、New API 等上游项目的许可义务。商业使用时，请同时遵守 One API 的 MIT 许可证、New API 的 AGPLv3 许可证及各上游项目的最新许可要求。 -
+如果你修改并通过网络向用户提供本项目服务，请理解并遵守 AGPLv3 对应的源码提供等义务。长期商用授权、机构合作或其他授权问题，请联系：maxapi@max-api.ai。 --- @@ -776,9 +356,9 @@ MAX API 不替代 Dify、LangChain、MCP Server、工作流引擎或业务 Agent ### 💖 感谢使用 MAX API -如果这个项目对你有帮助，欢迎给我们一个 ⭐ Star。 +如果这个项目对你有帮助，欢迎给我们一个 ⭐ Star、关注 Releases、提交可复现 Issue，或参与 MAX-API-Next 社区共建。 -**[官方文档](https://github.com/MAX-API-Next/MAX-API)** • **[问题反馈](https://github.com/MAX-API-Next/MAX-API/issues)** • **[最新发布](https://github.com/MAX-API-Next/MAX-API/releases)** +**[项目仓库](https://github.com/MAX-API-Next/MAX-API)** • **[参与共建](https://github.com/MAX-API-Next/MAX-API/issues)** • **[最新发布](https://github.com/MAX-API-Next/MAX-API/releases)** • **[MAX-API-Next 社区](https://github.com/MAX-API-Next)** Built with ❤️ by MAX-API-Next diff --git a/README.zh_TW.md b/README.zh_TW.md index d998efab..dbb555bc 100644 --- a/README.zh_TW.md +++ b/README.zh_TW.md @@ -1,13 +1,17 @@ -
+# MAX API -![max-api](/web/default/public/logo.png) +
-# MAX API +![MAX API](./web/default/public/logo.png) + +**面向 AGI 應用時代的 AI Models and Agents governance、智慧運維與開放協作基礎設施** + +**MAX API 2.0：開啟智慧運維時代 · 從統一模型閘道走向 AGI 原生治理與營運** -🍥 **AI 模型治理、AgentOps 與 AGI 應用服務基礎設施** +[查看 MAX API 2.0 Preview 發布說明](https://github.com/MAX-API-Next/MAX-API/releases/tag/v2.0.0-smartops.pre1)

- 簡體中文 | + 简体中文 | 繁體中文 | English | Français | @@ -30,736 +34,321 @@

- 專案定位 • - 發布渠道 • - 治理框架 • - 適用場景 • + ⭐ Star 專案 • + 💬 加入社群 • + 📚 查看文件 • + 🚀 取得版本 +

+ +

+ 加入社群 • 快速開始 • - 核心能力 • - 治理配置 • - 架構概覽 • - 模型與介面 • - 部署 • - FAQ • - 許可證 + 為什麼需要 • + AGI 技術方向 • + 目前能力 • + 智慧運維 • + Preview 部署

--- -## 📝 專案說明 - -MAX API 是由來自科研機構和高校的 AGI 愛好者組織發起、維護和長期營運的 AI 模型治理、AgentOps 與應用服務基礎設施專案，面向開發者、研究者、團隊和組織提供穩定、可復用的服務層能力。專案關注 AI 應用落地后的持續營運問題：模型越來越多、供應商介面頻繁變化、Agent 調用鏈路變長、成本和審計壓力增加。MAX API 在應用、Agent、使用者、組織和上游模型服務之間提供統一的接入、鑒權、路由、計費、觀測和治理層，讓 AI 應用更穩定、更可控地運行。 - -換句話說，MAX API 不只是請求轉發器，而是面向 AI-ready 應用和 Agent 工作負載的可營運網關：在統一模型協議與供應商差異的同時，把突發流量、長流式響應、大請求體、多節點緩存、成本審計和性能觀測放進同一套治理邊界。 - -持續投入方向： - -- **AI 模型治理**：持續跟蹤 OpenAI、Azure OpenAI、AWS Bedrock、Vertex AI、Ollama，以及 DeepSeek、通義千問 / 阿里云百煉、智譜 GLM、Kimi、豆包 / 火山引擎、騰訊混元、百度文心 / 千帆、訊飛星火、MiniMax、零一萬物、硅基流動等模型與平臺的模型更新、介面變化、參數差異、價格規則和任務協議；同時關注 Dify、RAGFlow、Kling、Seedance 等應用和多模態生態的接入形態，通過渠道、模型映射、協議轉換、路徑覆蓋和可配置任務協議，把分散模型能力納入統一治理。 -- **AI Agent 治理 / AgentOps**：圍繞 Agent、工作流和工具調用場景，持續完善令牌治理、模型訪問控制、調用追蹤、成本歸因、異常定位和日志審計，并為后續 MCP 風格工具 / 服務接入預留統一治理邊界，幫助 Agent 應用在真實業務中更可觀測、更可營運。 -- **渠道配置治理**：在渠道新建和編輯界面提供渠道能力矩陣與配置校驗，直觀展示 `chat/completions`、`responses`、`embeddings`、`rerank`、`video tasks`、模型發現等能力，并提前提示 Base URL、JSON 配置、Vertex AI 區域、Codex 憑證、視頻任務占位符等常見配置風險。 -- **營運優化與成本治理**：持續優化渠道路由、失敗重試、限流、預扣費、失敗退款、日志觀測、成本統計和運維分析；文本與多模態 token 場景可使用表達式計費和統一 JSON 配置，視頻等異步任務場景可使用參數化 rate-card，讓模型成本和 Agent 調用成本更直觀、可核算、可批量維護。 - -> [!IMPORTANT] -> - 面向公眾提供生成式人工智能服務時，使用者應遵守[《生成式人工智能服務管理暫行辦法》](http://www.cac.gov.cn/2023-07/13/c_1690898327029107.htm)等監管要求，并自行完成所在司法轄區要求的備案、許可、內容安全、實名、日志留存、稅務、支付和上游授權等合規義務。 -> - 日志審計、內容留存等敏感能力應僅在具備合法依據、明確告知、權限隔離和資料安全措施的場景下啟用。 -> - MAX API 提供模型與 Agent 工作負載的網關治理層，不提供上游模型賬號、密鑰、基礎模型訓練能力，也不替代 Dify、LangChain、MCP Server 等 Agent 編排或應用開發框架。 - ---- - -## 🚦 發布渠道 - -MAX API 當前版本發布分為正式版和 Preview 預覽版。Preview 預覽版用於提前開放新能力和修復，便於社群與部署者在真實環境中驗證相容性、穩定性和安全性；正式版會在對應 Preview 預覽版穩定運行 1 週後發布，以降低生產環境升級風險，保障系統安全性和可靠性。 - -生產環境建議優先使用正式版；需要提前驗證新功能、修復或相容性變化時，可在測試環境或灰度環境使用 Preview 預覽版，並在升級前做好資料庫備份和回滾預案。 - ---- - -## 🎯 專案定位 - -在 AGI 應用時代，MAX API 聚焦于開放的 AI 模型治理和 AI Agent 治理基礎設施，建設讓開發者和組織能夠穩定運行 AI 應用與 Agent 工作負載的服務、治理和營運層： - -- **模型治理平面**：統一管理模型入口、渠道、供應商、協議格式、模型映射、價格規則、任務協議和多模態介面。 -- **AgentOps 控制平面**：不替代 Agent 編排框架，而是在網關層為 Agent 工作負載提供令牌治理、模型訪問控制、調用日志、成本追蹤、異常定位和營運分析。 -- **渠道配置平面**：通過能力矩陣、表單校驗、模型發現和協議模板，降低新增上游渠道、遷移供應商和維護非標準介面時的誤配置風險。 -- **協議與供應商適配層**：持續跟蹤海外官方介面、國產模型平臺介面（DeepSeek、通義、智譜、火山引擎、百度千帆等）以及各類 OpenAI 兼容 / 非標準介面的變化，并規范化為穩定的應用側介面。 -- **成本、額度與可靠性治理**：支持渠道路由、加權分發、失敗重試、限流、預扣費、失敗退款，以及表達式計費、固定價格、任務 rate-card、倍率計費和用量統計。 -- **性能與可擴展性治理**：通過 Redis / 內存緩存、模型請求限流、流式超時與大響應緩衝、請求體上限、磁盤緩存、Pyroscope 性能采樣和優雅關閉，支撐單機到多節點部署的穩定運行。 -- **組織級營運與審計層**：為團隊、研究機構、企業和社區服務提供使用者管理、分組管理、私有化部署、資料留存、審計和持續營運優化能力。 -- **可復用治理模板**：沉淀渠道模板、任務協議模板、價格配置、部署實踐和運維經驗，降低新模型、新供應商和新 Agent 場景的接入成本。 - ---- - -## 🧠 治理框架 - -MAX API 的設計把 AI 模型和 AI Agent 的運行過程納入可配置、可觀測、可核算、可審計的治理框架。 - -| 治理對象 | MAX API 提供的能力 | 目標 | -|----------|-------------------|------| -| 模型資產 | 模型列表、模型映射、模型分組、模型限制、價格規則和多模態介面管理 | 讓組織知道“有哪些模型、誰能用、怎么計費、如何切換” | -| 上游渠道 | 供應商渠道、權重、分組、狀態、密鑰、Base URL、路徑覆蓋、能力矩陣、配置校驗、模型發現和失敗重試 | 降低單一供應商不可用、漲價、限流、誤配置或介面變化帶來的風險 | -| 協議格式 | OpenAI Compatible、Responses、Claude Messages、Gemini、Realtime、通用視頻任務協議等協議入口和轉換 | 讓應用側盡量面對穩定介面，而不是直接承擔各家協議差異 | -| Agent 令牌 | API Key、令牌分組、模型范圍、額度限制、過期時間和訪問控制 | 為 Agent、工作流和工具調用分配獨立、可回收、可限額的訪問憑據 | -| 用量與成本 | 請求日志、用量統計、表達式計費、分階段計費 JSON、任務 rate-card、預扣費和失敗退款 | 把模型調用成本拆到使用者、分組、令牌、模型、渠道和節點維度 | -| 異步任務 | 視頻等任務提交、輪詢、狀態映射、結果代理和任務計費 | 統一治理長耗時、多狀態、多上游格式的多模態任務 | -| 審計與安全 | 管理員側日志審計、錯誤日志、請求限制、流式超時、登錄與權限控制 | 在私有化部署和合規場景中提供可控的審計邊界，敏感內容審計集中放在安全與限制中管理 | -| 組織營運 | 使用者、分組、余額、支付、系統設置、資料看板和運維配置 | 支撐團隊、研究機構、企業或社區服務的持續營運 | - ---- - -## 🧩 適用場景 - -- **組織內部 AI 模型治理平臺**：統一管理使用者、令牌、模型、渠道、分組、權限、價格和賬單，避免每個團隊重復接入和維護上游服務。 -- **Agent 應用運行與治理底座**：為 Agent、工作流和工具調用應用提供穩定的模型網關、令牌隔離、成本控制、調用觀測、異常定位和審計基礎。 -- **國產模型與多供應商適配中心**：持續跟蹤國內外模型平臺介面和價格變化，通過渠道配置、模型映射、路徑覆蓋和協議模板降低適配成本。 -- **多模態任務治理平臺**：統一接入文本、圖像、視頻、音頻、嵌入、重排序、實時對話等介面，并對異步任務做狀態、結果代理和計費治理。 -- **模型成本與 Agent 成本核算平臺**：圍繞使用者、令牌、模型、渠道和分組進行額度分配、費用核算、賬單統計和成本分析。 -- **私有化與合規營運環境**：適合需要自主管理密鑰、資料、權限、日志、審計和計費策略的團隊或機構。 - ---- - -## 🚀 快速開始 - -默認使用 SQLite，本地體驗無需額外資料庫。 - -> [!WARNING] -> SQLite 僅適合本地體驗、開發和小規模測試。正式／生產環境不建議使用 SQLite：在併發請求、多實例部署、大量日志與用量資料、資料庫遷移、備份恢復或長事務場景下，可能出現鎖等待、寫入阻塞、遷移耗時或失敗，以及可用性和資料維護問題。正式環境請使用 MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6，並配置可靠的備份與恢復方案。 - -```bash -# 1. 拉取鏡像 -docker pull cscitechtop/max-api:latest - -# 2. 啟動服務，資料持久化到當前目錄 ./data -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest - -# 3. 訪問控制臺 -# 瀏覽器打開 http://localhost:3000 -``` - -生產部署建議使用 Docker Compose，并顯式配置資料庫、Redis、會話密鑰、加密密鑰和日志目錄。 - -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API - -# 按需修改 docker-compose.yml 中的資料庫、Redis 密碼和環境變量 -docker compose up -d -``` - -> [!WARNING] -> 將本專案作為面向公眾的生成式 AI 服務或 API 服務營運時，應先完成上游授權、備案、內容安全、實名、日志留存、稅務、支付和使用者協議等合規事項。 - ---- - -## ✨ 核心能力 - -### AI 模型治理 - -| 能力 | 說明 | -|------|------| -| 統一模型入口 | 支持 OpenAI 兼容介面、Responses、Claude Messages、Gemini、Realtime 等多種協議入口，應用側可通過統一網關訪問模型 | -| 多供應商模型池 | 海外可接入 OpenAI、Azure、Claude、Gemini、AWS Bedrock、Vertex AI、Ollama；國產方向持續跟蹤并內置 DeepSeek、通義千問、智譜 GLM、Kimi、豆包、騰訊混元、文心、訊飛星火、MiniMax、零一萬物、硅基流動等渠道適配 | -| 上游生態適配 | 支持 Codex、Dify、RAGFlow、Kling、Seedance 等應用、Agent 和多模態平臺相關介面的接入治理，便于把模型調用、工作流調用和異步任務納入統一網關 | -| 模型映射與訪問范圍 | 支持按渠道配置模型列表、模型映射、使用者分組、令牌分組和模型限制，讓不同團隊、應用或 Agent 使用不同模型集合 | -| 渠道能力矩陣 | 渠道編輯界面展示 `chat/completions`、`responses`、`Claude Messages`、`Gemini native`、`embeddings`、`images`、`audio`、`rerank`、`video tasks`、`model discovery` 等能力狀態，減少管理員對渠道能力的猜測 | -| 渠道配置校驗 | 在保存前檢查 API Key、模型列表、Base URL、額外配置、JSON 對象、Vertex AI 區域、Codex 憑證、模型發現能力和視頻任務路徑占位符等常見問題 | -| 多模態模型治理 | 支持聊天、圖像、視頻、音頻、嵌入、重排序、實時對話等場景，并對視頻等異步任務提供提交、輪詢、狀態映射和結果代理 | -| 通用視頻任務協議 | 支持將不同視頻上游的任務提交、查詢、進度、狀態映射、錯誤消息和結果 URL 路徑統一配置到渠道中；請求體透傳和改寫復用渠道設置，默認路徑為 `/v1/videos/create` 與 `/v1/videos/{task_id}` | -| 協議轉換與自定義上游 | 支持 OpenAI Compatible、Responses、Chat Completions、Claude Messages、Gemini 等格式之間的轉換與適配，也支持配置合法授權的上游地址、路徑覆蓋和任務協議解析規則 | - -### AI Agent 治理 / AgentOps - -| 能力 | 說明 | -|------|------| -| Agent 令牌隔離 | 可為 Agent、工作流、插件、工具調用或使用者創建獨立 API Key，并配置模型范圍、額度、過期時間和分組 | -| 模型訪問控制 | 通過使用者、令牌、分組、模型限制和渠道策略控制 Agent 能調用哪些模型、走哪些渠道、消耗多少額度 | -| 調用鏈路觀測 | 提供請求日志、用量統計、渠道命中、耗時、錯誤和重試信息，幫助定位 Agent 調用失敗、成本異常和上游波動 | -| 成本歸因 | 支持按模型、渠道、使用者、分組、令牌和節點維度統計成本與用量，方便核算不同 Agent、業務線或部署節點成本 | -| 管理員審計 | 私有部署場景可按合規要求啟用管理員側日志審計能力，普通使用者日志介面會過濾管理員專用審計字段 | -| 營運看板 | 提供面向管理員的統計分析、使用者管理、渠道管理、系統設置和運維分析能力 | - -### 成本、計費與可靠性治理 - -**模型價格表達式** - -- **一行表達式 = 一個 token 模型的完整計價規則**：階梯定價、緩存命中、圖像 / 音頻 token 分項、分時折扣、按請求頭或參數動態加價，全部寫在同一行，適合維護復雜模型價格。 -- **價格即真實價格**：系數直接填寫「美元 / 百萬 token」，`p * 2.5` 就是輸入每百萬 token 2.5 美元，適合按上游價格表維護成本；傳統倍率模式仍保持兼容。 -- **可視化 + 原始雙模式編輯**：既可逐項填價格、按檔位設條件，也可直接編輯表達式，并內置常見模型預設模板。 -- **統一 JSON 批量維護**：支持在一個 `Tiered billing JSON` 窗口中維護多個模型的分階段計費規則，保存時原子更新 `billing_mode` 與 `billing_expr`，避免手動維護多個配置項時出現不同步。 -- **自動 token 歸一**：按上游格式（OpenAI / Claude）和表達式實際用到的變量，自動從輸入/輸出中剝離緩存、圖像、音頻等子類別，避免重復計費；日志中可還原命中的計價檔位與明細。 - -**任務計費、傳統計費與可靠性** - -- 支持視頻等異步任務的參數化 rate-card 計費，按模型、供應商、時長、質量、音頻、視頻輸入等字段匹配單價；可通過 `task_billing_setting.rate_cards` 的 JSON 窗口統一維護，并用 `vendor` 字段區分 Sora、Veo、Seedance、Kling 等供應商分區。 -- 兼容按量、按次、緩存命中等計費模式，以及模型倍率、分組倍率、渠道倍率。 -- 支持預扣費、失敗退款、異常處理和消費日志，適合長耗時 Agent 調用鏈路和異步多模態任務。 -- 支持渠道加權隨機、失敗重試、禁用渠道繞過和模型級路由，降低上游異常對應用和 Agent 的影響。 -- 支持 Redis 緩存與內存緩存，適配單機和多機部署。 - -### 性能與可擴展性治理 - -| 能力 | 說明 | -|------|------| -| 緩存與多節點擴展 | 單機可使用內存緩存，多機可接入 Redis；使用者、令牌、渠道親和、額度相關緩存減少重復資料庫訪問，并通過 `SESSION_SECRET`、`CRYPTO_SECRET`、`NODE_NAME` 保持會話、加密和日志歸屬一致 | -| 請求限流與容量保護 | 支持全局 API / Web 限流、關鍵介面限流、搜索限流、模型請求限流和按分組配置的模型請求配額；可使用 Redis 或內存計數器 | -| 流式與大請求控制 | 支持 `STREAMING_TIMEOUT`、`STREAM_SCANNER_MAX_BUFFER_MB`、`MAX_REQUEST_BODY_MB`、`MAX_FILE_DOWNLOAD_MB` 等配置，控制長流式響應、大行 SSE、解壓后請求體和遠程文件下載大小 | -| 中繼連接調優 | 支持 `RELAY_TIMEOUT`、`RELAY_IDLE_CONN_TIMEOUT`、`RELAY_MAX_IDLE_CONNS`、`RELAY_MAX_IDLE_CONNS_PER_HOST` 配置上游 HTTP 連接池與超時策略 | -| 磁盤緩存與性能觀測 | 系統性能設置可啟用大請求體磁盤緩存、配置緩存閾值和容量；運維介面可查看 / 清理磁盤緩存，并可通過 Pyroscope 采集 CPU、內存、goroutine、mutex 和 block profile | -| 平滑退出與資料落盤 | 關閉進程時支持 `SHUTDOWN_TIMEOUT_SECONDS` 和 `QUOTA_DATA_CACHE_SAVE_TIMEOUT_SECONDS`，盡量在退出前完成 HTTP 關閉和額度緩存保存 | - -### 安全與組織管理 - -- 支持 JWT、WebAuthn/Passkeys、OAuth、OIDC、Telegram、Discord、LinuxDO 等登錄方式。 -- 支持管理員、普通使用者、分組、令牌和模型訪問控制。 -- 支持請求體大小限制、流式超時控制、錯誤日志和運行狀態檢查。 -- 支持多機部署下的統一會話密鑰、加密密鑰和 Redis 共享緩存。 +MAX API 位於應用程式、Agent 與上游模型服務之間，是統一的模型閘道、治理控制平面和營運入口。MAX-API-Next 社群圍繞 AGI 工程化持續建設本專案，並向開發者、研究者、企業工程團隊、大學技術愛好者與開源貢獻者開放協作。我們的目標是建設 AGI 應用真正需要的模型接入、權限、成本、Evidence、智慧運維和安全控制基礎。 ---- +我們將在 AGI 領域：**持續交付先進且可驗證的技術、將真實生產問題沉澱為開放工程能力、建立能夠共同研究與貢獻的社群。** -## 🆚 為什麼使用網關 +## 🌐 加入 MAX-API-Next 社群 -| 維度 | 直連各家官方 SDK / API | 通過 MAX API 網關 | -|------|------------------------|-------------------| -| 模型接入 | 每家一套 SDK、鑒權和參數 | 統一模型入口，一次接入，多模型復用 | -| 模型治理 | 模型清單、價格、權限和渠道分散在各平臺 | 統一管理模型、渠道、映射、分組、額度和價格規則 | -| Agent 訪問 | Agent 直接持有上游 Key，難以回收和限額 | 為 Agent 分配獨立令牌，并限制模型、額度、過期時間和分組 | -| 協議差異 | 應用自行適配 Claude、Gemini、Responses 等格式 | 網關統一做協議轉換和供應商適配 | -| 失敗處理 | 應用自行實現重試、降級和錯誤歸一 | 渠道失敗自動重試、加權路由和錯誤處理 | -| 性能與擴展 | 應用自行處理超時、限流、連接池和緩存 | 網關集中提供流式超時、請求限制、Redis / 內存緩存、連接池調優和性能觀測 | -| 成本統計 | 各平臺賬單分散，難以按使用者或 Agent 核算 | 統一額度、計費、用量統計和消費日志，可按令牌和模型歸因 | -| 審計邊界 | 應用側分散記錄，權限和留存策略不統一 | 管理員側統一審計入口，普通使用者日志過濾管理員專用字段 | -| 私有化 | 密鑰、日志和計費策略分散 | 自托管，自主掌控密鑰、資料、日志和策略 | +MAX API 不只是一個程式碼倉庫，也是一項面向 AI Models、Agents、AgentOps 與 AGI 工程化的長期開放協作。無論你正在部署模型閘道、開發 Agent、適配新模型、研究評測與治理，或願意改善文件和國際化，都歡迎加入社群交流並參與共建。 ---- - -## 🧭 架構概覽 - -MAX API 采用分層架構：應用、SDK 或 Agent 請求經統一入口進入，依次經過路由、中間件、控制器和業務服務層，最終由中繼層適配到對應上游供應商；資料層和緩存層為模型治理、Agent 令牌治理、計費、日志、審計和任務狀態提供持久化與加速能力。 - -```mermaid -flowchart LR - Client[客戶端 / SDK / Agent] --> Router[Router
路由] - Router --> MW[Middleware
鑒權 · 限流 · 分發 · 日志] - MW --> Ctrl[Controller
請求處理器] - Ctrl --> Svc[Service
模型治理 · AgentOps · 計費審計] - Svc --> Relay[Relay
中繼 / 協議轉換] - Relay --> Adapters[Channel 適配器
OpenAI · Claude · Gemini · 國產平臺 · 自定義上游] - Adapters --> Upstream[(上游模型服務)] - Svc --> Model[Model
GORM] - Model --> DB[(SQLite · MySQL · PostgreSQL)] - Svc --> Cache[(Redis · 內存緩存)] -``` - -### 目錄結構 - -| 目錄 | 職責 | -|------|------| -| `router/` | HTTP 路由，包含 API、relay、dashboard 和 web 入口 | -| `controller/` | 請求處理器，負責參數解析、鑒權后的業務入口和響應封裝 | -| `service/` | 業務邏輯，包含模型治理、AgentOps、日志、計費、審計、任務、渠道和系統配置等能力 | -| `model/` | 資料模型與資料庫訪問，基于 GORM 兼容 SQLite、MySQL、PostgreSQL | -| `relay/` | AI API 中繼、協議轉換和供應商適配 | -| `relay/channel/` | 各供應商適配器，如 openai、claude、gemini、aws 等 | -| `middleware/` | 鑒權、限流、CORS、日志、請求分發和上下文處理 | -| `setting/` | 模型價格、任務計費、營運、系統、安全和性能配置 | -| `common/` | JSON、加密、Redis、限流、環境變量等共享工具 | -| `dto/` / `types/` | 請求、響應、錯誤和中繼格式類型定義 | -| `constant/` | API 類型、渠道類型、上下文鍵等常量 | -| `i18n/` / `oauth/` / `pkg/` | 后端國際化、OAuth 實現和內部包 | -| `web/` | 前端主題容器，默認主題位于 `web/default/` | - -### 技術棧 - -| 層 | 技術 | -|------|------| -| 后端 | Go 1.25+、Gin、GORM v2 | -| 前端 | React 19、TypeScript、Rsbuild、Base UI、Tailwind CSS | -| 包管理 | Bun workspace | -| 資料庫 | SQLite / MySQL ≥ 5.7.8 / PostgreSQL ≥ 9.6 | -| 緩存 | Redis + 內存緩存 | -| 鑒權 | JWT、WebAuthn/Passkeys、OAuth、OIDC | - ---- - -## 🤖 AI 模型與介面支持 - -> 實際可用模型取決于你的上游授權、渠道配置、模型映射和服務商支持情況。MAX API 的重點是把這些模型能力納入統一治理，而不是提供上游模型服務本身。 - -| 類型 | 說明 | -|------|------| -| OpenAI-Compatible | Chat Completions、Embeddings、Images、Audio 等兼容介面，可作為多數應用和 Agent 的通用模型入口 | -| OpenAI Responses | Responses 格式請求、中繼與 Responses ↔ Chat Completions 兼容轉換，適合逐步接入新的 OpenAI 應用協議 | -| Claude Messages | Claude Messages 格式與 OpenAI 兼容格式轉換，降低應用側多協議維護成本 | -| Google Gemini | Gemini 聊天、文本，以及 `/v1/responses` 兼容轉換能力 | -| Azure OpenAI | Azure OpenAI 與 Realtime 相關介面 | -| AWS Bedrock | Bedrock Runtime 相關模型接入 | -| 上游平臺和應用生態 | AWS、Azure、Vertex、Ollama、Codex、Dify、RAGFlow、Kling、Seedance 等平臺或應用形態可按渠道能力接入治理 | -| 國產模型與平臺 | 內置 DeepSeek、通義千問 / 阿里云百煉、智譜 GLM、Kimi、豆包 / 火山引擎、騰訊混元、百度文心 / 千帆、訊飛星火、MiniMax、零一萬物、硅基流動等適配器或兼容接入能力 | -| `rerank` | Cohere、Jina 等重排序模型，可用于檢索增強和 Agent 檢索鏈路 | -| Midjourney / Suno / Dify | 圖像、音樂、工作流等服務適配 | -| 視頻任務介面 | 支持 `/v1/videos/create`、`/v1/videos/{task_id}` 等視頻生成任務的提交、請求體透傳或參數覆蓋、輪詢、狀態映射、結果代理和參數化任務計費 | -| 自定義上游 | 支持配置合法授權的上游介面地址、協議適配規則、Responses / Chat 轉換、路徑覆蓋、狀態映射、錯誤消息路徑和任務結果解析 | +**加入社群，你可以更快取得版本動態、模型與協定變化、部署經驗、問題排查線索和社群共建機會。** -### 支持的主要介面 +

+ QQ 群：950126533 • + 微信群：搜尋 MAX-API +

-
-查看介面類別 - -- 聊天介面：`/v1/chat/completions` -- 響應介面：`/v1/responses` -- 圖像介面：`/v1/images/*` -- 音頻介面：`/v1/audio/*` -- 視頻介面：`/v1/videos/*` -- 嵌入介面：`/v1/embeddings` -- 重排序介面：`/v1/rerank` -- 實時對話：OpenAI Realtime 兼容介面 -- Claude Messages：Claude 原生格式入口 -- Gemini：Google Gemini 格式入口 +| 社群入口 | 用途 | +|---|---| +| [MAX-API-Next GitHub](https://github.com/MAX-API-Next) | 關注社群專案、技術方向與開放協作 | +| [MAX API Issues](https://github.com/MAX-API-Next/MAX-API/issues) | 提交可重現問題、需求建議與相容性變化 | +| [MAX API Releases](https://github.com/MAX-API-Next/MAX-API/releases) | 取得正式版與 Preview 版本動態 | +| [Ask DeepWiki](https://deepwiki.com/MAX-API-Next/MAX-API) | 快速檢索與理解專案程式碼 | +| 技術與生態合作 | 聯絡 `maxapi@max-api.ai` | -
+### 我們正在尋找這些共建者 -### Reasoning Effort 支持 +- **模型與協定貢獻者**：適配新模型、新供應商、Reasoning、工具呼叫和多模態任務協定。 +- **Agent 與應用開發者**：分享 Dify、RAGFlow、Codex、MCP、工作流程和研究 Agent 的接入與治理實踐。 +- **可靠性與安全工程師**：完善跨資料庫測試、非同步任務復原、結算安全、快取一致性和權限邊界。 +- **文件與社群貢獻者**：改善部署教學、FAQ、案例、翻譯、可重現實驗和新貢獻者指引。 +- **研究者與評測開發者**：共建 Evidence、Evaluator、Detector、Runbook 和受控自治方案。
-查看示例模型命名 - -**OpenAI 系列：** +查看共建方向、協作原則與參與方式 -- `o3-mini-high` -- `o3-mini-medium` -- `o3-mini-low` -- `gpt-5-high` -- `gpt-5-medium` -- `gpt-5-low` +| 共建方向 | 適合的貢獻 | +|---|---| +| 模型與供應商生態 | 模型/協定適配、相容性測試、模型清單與棄用變化、渠道設定範本 | +| AgentOps 與 AGI 應用治理 | Agent 接入範例、權杖與權限邊界、成本治理和運行實踐 | +| SmartOps 與 Evidence | 脫敏故障樣本、指標口徑、告警規則、資料品質說明、診斷與評測方法 | +| 可靠性、計費與安全 | 冪等結算、非同步任務復原、跨資料庫迴歸、快取一致性和高風險操作驗證 | +| 文件、教學與國際化 | 部署教學、架構說明、FAQ、案例、翻譯和新貢獻者指引 | -**Claude 思考模型：** +協作時請盡量提供最小重現、版本、環境、脫敏日誌或測試證據；協定、資料庫和使用者契約變更需要說明相容性、遷移與回復路徑。請勿提交真實 API Key、客戶資料、支付原始記錄、私人日誌或未經授權的資料。涉及資金、安全、金鑰、生產資料或自動執行的貢獻，需要更嚴格的測試、獨立審查和明確責任人。 -- `claude-3-7-sonnet-20250219-thinking` +你可以從以下方式開始： -**Gemini 系列：** - -- `gemini-2.5-flash-thinking` -- `gemini-2.5-flash-nothinking` -- `gemini-2.5-pro-thinking` -- `gemini-2.5-pro-thinking-128` -- 也可以在 Gemini 模型名后追加 `-low`、`-medium`、`-high` 來控制思考力度。 +1. 提交一個可重現的問題、協定差異或模型相容性變化。 +2. 為既有問題補充失敗測試、跨資料庫案例、前端迴歸或脫敏 Evidence。 +3. 完善模型/渠道設定、部署說明、FAQ、架構文件或多語言翻譯。 +4. 分享經過脫敏的 Agent 接入、成本治理、SmartOps 和私有化部署實踐。 +5. 提交 Evaluator、Detector、Runbook 或受控自治設計提案，並明確能力邊界與風險。
---- - -## 🔧 治理配置 - -### 初始治理配置建議 - -1. 部署完成后進入控制臺，創建或確認管理員賬號。 -2. 配置系統設置、使用者注冊策略、登錄方式和安全限制。 -3. 添加上游渠道，填寫合法授權的 API Key、Base URL、模型列表、模型映射和渠道設置。 -4. 根據組織結構配置使用者分組、令牌分組、模型限制、額度策略和價格規則，將模型能力納入訪問控制。 -5. 為應用、Agent 或工作流創建獨立令牌，按業務線、環境或風險級別配置模型范圍和額度。 -6. 在營運設置中配置失敗重試、日志記錄、緩存策略和消費統計。 -7. 如需管理員側內容審計，應在合規前提下進入“系統設置 → 安全與限制 → 日志審計”啟用，并確保“記錄配額使用量（日志維護）”已開啟。 - -### 渠道能力矩陣與配置校驗 - -渠道新建或編輯時，系統會根據渠道類型展示能力矩陣，并給出實時配置校驗結果。矩陣中的介面名稱保留原始技術表述，例如 `chat/completions`、`responses`、`embeddings`、`rerank`、`video tasks`，說明文字使用中文，便于管理員判斷當前渠道能承擔哪些模型和任務。 - -配置校驗覆蓋以下常見問題： - -- 新建渠道缺少 API Key、模型列表為空、需要 Base URL 或額外配置但未填寫。 -- Base URL 誤填到 `/v1` 結尾，導致系統再次拼接上游路徑。 -- `setting`、`param_override`、`header_override`、`settings` 等字段不是 JSON 對象。 -- Vertex AI 區域配置缺少 `default`，或服務賬號密鑰不是有效 JSON。 -- Codex 渠道憑證缺少 `access_token` 或 `account_id`。 -- 當前渠道不支持模型發現，但開啟了上游模型檢查或自動同步。 -- 視頻任務查詢路徑缺少 `{task_id}`、`{operation_name}` 或 `{upstream_task_id}` 占位符。 - -### 通用視頻任務協議 - -視頻模型供應商的介面經常在路徑、任務 ID、狀態字段、進度字段、錯誤字段和結果 URL 字段上不一致。MAX API 將原先面向單一模型的任務協議能力擴展為通用視頻任務協議，適用于 OpenAI、Ali、Gemini、MiniMax、Vertex AI、VolcEngine、Kling、Jimeng、Vidu、Doubao Video、Sora 等視頻任務渠道。 - -支持的配置層級： - -- **僅路徑覆蓋**：只配置 `submit_path` 和 `query_path`，系統仍使用對應渠道的官方響應解析邏輯，適合只改上游路徑的兼容渠道。 -- **完整協議解析**：設置 `task_protocol = "generic_video_task"`，同時配置任務 ID、狀態、進度、結果 URL、錯誤消息和狀態映射路徑，適合非標準視頻任務響應。 -- **請求體處理**：通用視頻任務協議不再單獨定義請求體生成模式。需要原樣透傳客戶端 JSON 時使用渠道設置里的 `Pass Through Body`；需要字段改寫、默認值或 header 聯動時使用已有的 `Param Override`。 - -默認任務路徑： - -```json -{ - "task_protocol": "generic_video_task", - "task_protocol_config": { - "submit_path": "/v1/videos/create", - "query_path": "/v1/videos/{task_id}", - "task_id_path": "task_id", - "status_path": "status", - "progress_path": "progress", - "result_url_paths": [ - "result.primary_url", - "result.urls.0", - "data.result.primary_url", - "url", - "video_url", - "download_url" - ], - "error_message_path": "error_message", - "status_map": { - "queued": "QUEUED", - "running": "IN_PROGRESS", - "succeeded": "SUCCESS", - "failed": "FAILURE" - } - } -} -``` +配套文件：[MAX-API-Docs](https://github.com/MAX-API-Next/MAX-API-Docs)（部署、設定與使用說明）。 -查詢路徑支持 `{task_id}`、`{operation_name}`、`{upstream_task_id}`。其中 `{operation_name}` 可保留多段路徑值，適合 Gemini / Vertex 風格的 operation 查詢介面。視頻內容可通過 `/v1/videos/{task_id}/content` 代理讀取；在需要隱藏上游資源域名的部署中，建議讓終端使用者訪問該內容代理地址，并配合鑒權、SSRF 防護和允許端口配置使用。 +歡迎模型廠商、Agent/工作流程專案、開源社群、研究者和企業工程團隊展開技術共建。正式合作、聯合發布或以機構名義使用，應取得雙方明確授權。 -### 計費 JSON 維護 - -系統設置中的模型計費支持兩類 JSON 統一維護入口： - -- **分階段計費 JSON**：通過 `Tiered billing JSON` 統一維護多個模型的 `{ enabled, expr }` 配置，保存時同步更新 `billing_mode` 與 `billing_expr`。 -- **任務 rate-card JSON**：通過 `task_billing_setting.rate_cards` 統一維護異步任務計費規則，可按 `vendor` 分區維護 Sora、Veo、Seedance、Kling 等視頻模型的不同計費表。 - -Seedance 2.0 等視頻模型可按分辨率、視頻輸入等請求參數參與倍率或 rate-card 計算；使用透傳或參數覆蓋時，應確保最終提交給上游的字段與計費字段保持一致。 +> [!IMPORTANT] +> 面向公眾提供生成式人工智慧服務時，使用者應自行完成所在司法管轄區要求的上游授權、備案許可、內容安全、實名、日誌留存、稅務、支付和使用者協議等合規義務。日誌稽核和內容留存僅應在具備合法依據、明確告知、權限隔離和資料安全措施的場景中啟用。 -示例結構： +MAX API 管理控制台 -```json -{ - "model-name": { - "enabled": true, - "expr": "len <= 200000 ? tier(\"standard\", p * 3 + c * 15) : tier(\"long_context\", p * 6 + c * 22.5)" - } -} -``` +## 🧠 面向 AGI 的技術方向 -任務 rate-card 可按請求參數匹配價格： - -```json -{ - "vendor/model-name": { - "vendor": "kling", - "unit": "second", - "quantity_field": "duration", - "default_quantity": 5, - "strict": true, - "defaults": { - "quality": "std", - "has_audio": "false" - }, - "rows": [ - { - "id": "std_no_audio", - "match": { - "quality": "std", - "has_audio": "false" - }, - "unit_price": 0.6 - } - ] - } -} -``` +AGI 應用不會長期依賴單一模型、單一協定或一次性請求。它們需要跨模型推理、工具呼叫、多模態任務、長時間運行、成本約束、生產 Evidence 和可復原的失敗處理。MAX API 選擇從這些可驗證的工程問題出發，建設 AI Models and Agents governance 基礎。 -### 常見運維入口 +| 技術方向 | 目前基礎 | 對 AGI 應用的價值 | +|---|---|---| +| 多模型與多協定接入 | OpenAI Compatible、Responses、Claude Messages、Gemini、Realtime、多模態與非同步任務協定 | 讓應用和 Agent 面對相對穩定的入口，並能隨模型生態變化持續遷移 | +| 推理與工具上下文相容 | Reasoning Effort、工具定義、Tool Call、工具回應關聯和多輪上下文轉換 | 減少跨供應商切換時推理資訊與工具呼叫語意遺失 | +| 治理控制平面 | 使用者、權杖、模型範圍、分組、路由、限流、額度、價格和管理員權限 | 為不同 Agent、環境和任務建立獨立身分、存取邊界與預算邊界 | +| 可復原計費與任務生命週期 | 預扣、最終結算、冪等記錄、失敗退款、非同步任務輪詢和人工對帳狀態 | 避免長任務、重試和異常時間窗造成重複扣費、錯誤退款或不可追溯結果 | +| Evidence 與智慧運維 | 日誌、錯誤、重試、效能桶、活動告警、渠道/模型效能和結算證據 | 讓診斷、評測和未來 Agent 建議建立在可追溯事實上，而不是只依賴提示詞推斷 | +| 安全與組織治理 | Passkey、2FA、分作用域重新驗證、工作階段撤銷、稽核和敏感操作限流 | 為高風險設定、憑證和營運操作保留明確責任邊界 | +| 受控自治與工程進化 | **長期藍圖**：Policy、Budget、Approval、Shadow、Canary、Rollback、隔離 Coding Workspace | 讓自動化能力先被評測、約束和稽核，再逐步進入低風險生產動作 | -| 功能 | 說明 | -|------|------| -| 渠道管理 | 配置上游供應商、模型映射、渠道權重、密鑰、協議路徑和狀態，并通過能力矩陣與配置校驗提前發現風險 | -| 模型與價格 | 維護模型列表、模型價格、表達式計費、分階段計費 JSON、任務 rate-card JSON 和模型展示信息 | -| 令牌管理 | 為應用、Agent、工作流、工具調用或使用者創建訪問令牌并限制模型與額度 | -| 使用者管理 | 管理使用者、分組、余額、權限和狀態 | -| 使用日志 | 查看調用記錄、消耗、耗時、錯誤、渠道命中和管理員可見的審計信息 | -| 系統設置 | 管理安全限制、日志審計、模型定價、任務計費、營運策略、日志維護、支付和站點配置 | -| 資料看板 | 查看整體請求量、模型用量、消費趨勢、渠道狀態和 Agent 令牌成本 | +### 技術原則 ---- +- **Evidence before Action**：先建立可驗證事實，再進行診斷、建議或自動動作。 +- **Governance before Autonomy**：身分、權限、預算、審批、稽核和回復必須先於自治能力。 +- **One Billing Truth**：生產計費、額度與結算保持單一事實來源，不為 Agent 或外掛建立第二套帳務邏輯。 +- **Compatibility by Design**：持續支援 SQLite、MySQL、PostgreSQL、多供應商協定和可遷移的應用端契約。 +- **Open Collaboration, Safe Boundaries**：開放協定適配、測試、文件、評測和治理方案，高風險生產、資金、金鑰與發布動作仍由明確責任人審批。 -## 🚢 部署 +### MAX API 2.0 技術亮點 -### 部署要求 +- **Evidence-driven SmartOps**：將資源告警、渠道/模型效能、資料品質狀態和計費結算證據匯聚到統一運維入口，並保留人工審閱與真實財務狀態之間的邊界。 +- **面向先進模型協定持續演進**：增強 Responses、Claude Messages、Gemini 與 Ollama 的 Reasoning、快取鍵、懲罰參數、工具定義和多輪 Tool Context 相容。 +- **可復原的計費與非同步任務語意**：透過冪等 settlement、持久化 effect、任務 ID 和明確的 pending/manual 狀態，避免異常重試導致重複扣費、錯誤退款或任務遺失。 +- **高風險操作分作用域重新驗證**：Passkey、2FA、Telegram、API Token 與工作階段撤銷採用 scope-bound step-up verification，並透過 `session_generation` 及時撤銷舊工作階段。 +- **跨資料庫與持續驗證**：核心資料路徑相容 SQLite、MySQL 和 PostgreSQL；Go 測試、前端 Bun 測試、TypeScript 型別檢查、JSON 包裝規則和測試鏡像同步共同構成發布門檻。 -| 組件 | 要求 | -|------|------| -| 容器引擎 | Docker / Docker Compose | -| 本地資料庫 | SQLite，僅用於本地體驗、開發或小規模測試；Docker 部署時需掛載 `/data` | -| 正式環境資料庫 | MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6，並配置可靠的備份與恢復方案 | -| 緩存 | 單機可使用內存緩存，多機部署建議使用 Redis | -| 前端構建 | 使用 Bun workspace，需保留 `web/package.json` 與 `web/bun.lock` | -| 源碼構建 | 使用倉庫 `go.mod` 聲明的 Go 版本（目前 Go 1.25.1+）和 `go.sum`；依賴或安全更新後運行 `go mod download`、`go mod verify` 並重新構建 | +## 💡 為什麼需要 MAX API -### 推薦環境變量 +| 維度 | 直接連接多個供應商 | 使用 MAX API | +|---|---|---| +| 應用接入 | 分別維護 SDK、協定、鑑權和錯誤格式 | 應用端使用相對穩定的統一入口 | +| 模型切換 | 修改程式碼、金鑰和部署設定 | 透過渠道、模型映射、分組和路由調整 | +| 可用性 | 每個應用自行處理重試和上游故障 | 集中設定權重、優先級、失敗重試和切換 | +| 權限與金鑰 | 憑證散落在應用和環境變數中 | 集中管理權杖、模型範圍、額度和有效期 | +| 成本核算 | 多家帳單分散，難以歸因 | 按使用者、權杖、模型、渠道和分組統計 | +| 故障排查 | 日誌分散，跨供應商定位困難 | 在閘道端統一觀察請求、錯誤、重試和耗時 | -
-查看常用環境變量 - -| 變量名 | 說明 | 默認值 | -|--------|------|--------| -| `SESSION_SECRET` | 會話密鑰，多機部署必須設置 | - | -| `CRYPTO_SECRET` | 加密密鑰，使用 Redis 或多機部署時必須設置 | - | -| `SQL_DSN` | 資料庫連接字符串 | - | -| `REDIS_CONN_STRING` | Redis 連接字符串 | - | -| `STREAMING_TIMEOUT` | 流式響應超時時間，單位秒 | `300` | -| `STREAM_SCANNER_MAX_BUFFER_MB` | 流式掃描器單行最大緩沖，圖像 base64 等大響應可適當調大 | `64` | -| `MAX_REQUEST_BODY_MB` | 請求體最大大小，按解壓后大小計算，超出返回 `413` | `32` | -| `AZURE_DEFAULT_API_VERSION` | Azure API 默認版本 | `2025-04-01-preview` | -| `ERROR_LOG_ENABLED` | 錯誤日志開關 | `false` | -| `NODE_NAME` | 節點名稱，多機部署時用于日志定位和異步任務結算歸屬 | - | -| `PYROSCOPE_URL` | Pyroscope 服務地址 | - | -| `PYROSCOPE_APP_NAME` | Pyroscope 應用名 | `max-api` | -| `PYROSCOPE_BASIC_AUTH_USER` | Pyroscope Basic Auth 使用者名 | - | -| `PYROSCOPE_BASIC_AUTH_PASSWORD` | Pyroscope Basic Auth 密碼 | - | -| `PYROSCOPE_MUTEX_RATE` | Pyroscope mutex 采樣率 | `5` | -| `PYROSCOPE_BLOCK_RATE` | Pyroscope block 采樣率 | `5` | -| `HOSTNAME` | Pyroscope 標簽中的主機名 | `max-api` | +一句話概括：**供應商負責提供模型，Agent 框架負責編排業務，MAX API 負責統一接入並守住治理邊界。** -
+## 🚀 快速開始 -### Docker Compose +本機體驗預設使用 SQLite，只需 Docker： ```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API - -# 修改 docker-compose.yml： -# - 更換 PostgreSQL / MySQL / Redis 默認密碼 -# - 按需設置 SESSION_SECRET、CRYPTO_SECRET、NODE_NAME -# - 生產環境建議配置反向代理與 HTTPS -docker compose up -d -``` - -### Docker 命令 +MAX_API_IMAGE=cscitechtop/max-api:latest@sha256:006d5d86887a261baab4d71ec3797d429e3771a4836e5899734aee0e7f66f2ab -**SQLite：** +docker pull "$MAX_API_IMAGE" -```bash -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest +docker run --name max-api -d --restart always -p 127.0.0.1:3000:3000 -e TZ=Asia/Shanghai -v ./data:/data "$MAX_API_IMAGE" ``` -**MySQL：** +啟動後存取： -```bash -docker run --name max-api -d --restart always \ - -p 3000:3000 \ - -e SQL_DSN="root:123456@tcp(mysql:3306)/max-api" \ - -e TZ=Asia/Shanghai \ - -v ./data:/data \ - cscitechtop/max-api:latest -``` +接著完成三件事： -### 從源碼構建鏡像 - -```bash -git clone https://github.com/MAX-API-Next/MAX-API.git -cd MAX-API -docker build -t cscitechtop/max-api:latest . -``` - -> [!NOTE] -> `Dockerfile` 會在鏡像構建中下載 Go 模塊。宿主機直接構建或依賴 / 安全更新後，請保持 `go.mod` 與 `go.sum` 成對提交，先運行 `go mod download && go mod verify`，再重新構建二進制或鏡像；需要刷新基礎鏡像時可使用 `docker build --pull --no-cache -t cscitechtop/max-api:latest .`。 +1. 建立或確認管理員帳號。 +2. 新增一個具有合法授權的上游渠道和 API Key。 +3. 建立存取權杖，將應用中的 Base URL 指向 MAX API。 > [!TIP] -> 前端使用 Bun workspace。構建上下文中必須保留 `web/package.json`、`web/bun.lock` 和 `web/default/package.json`，否則 `catalog:` 依賴無法解析。 - -### 多機部署注意事項 - +> 生產環境建議使用正式版。Preview 版本用於測試和灰度驗證，升級前請備份資料庫並準備回復方案。 +> > [!WARNING] -> - 必須設置相同的 `SESSION_SECRET`，否則不同節點之間登錄狀態不一致。 -> - 使用共享 Redis 時必須設置相同的 `CRYPTO_SECRET`，否則加密資料無法解密。 -> - 多節點建議設置穩定的 `NODE_NAME`，便于在日志、審計信息和異步任務結算中定位來源節點。 -> - 生產環境應使用外部資料庫、外部 Redis、HTTPS 反向代理和可靠的備份策略。 - ---- +> SQLite 適合本機體驗、開發和小規模測試。正式環境建議使用仍在供應商安全支援週期內的 MySQL（建議 8.4 LTS）或 PostgreSQL（建議 14+），並設定 Redis、HTTPS、備份和復原方案。專案相容性下限仍為 MySQL ≥ 5.7.8、PostgreSQL ≥ 9.6，但不建議將其用於生產環境。 -## 🗺️ 路線圖 +## ✨ 目前能力 -以下為方向性規劃，會根據維護節奏、真實場景和社區需求調整，不構成時間承諾。 +以下能力已在目前系統中提供： -- **模型治理深化**：圍繞模型目錄、模型價格、模型權限、模型映射、模型能力標簽和供應商變更，持續增強治理能力。 -- **AgentOps 深化**：圍繞 Agent、工具調用、工作流和 MCP 風格工具 / 服務接入，持續優化調用鏈路、成本歸因、異常定位和治理能力。 -- **多模態任務治理**：增強圖像、視頻、音頻和實時交互任務的計費、限流、狀態追蹤和結果代理。 -- **協議轉換增強**：持續完善 OpenAI Compatible、Responses、Claude Messages、Gemini 等協議之間的轉換。 -- **國產模型與平臺跟蹤適配**：跟進國產模型、云平臺、價格規則和 API 協議變化，沉淀可復用的渠道、價格和任務協議配置。 -- **供應商適配模板化**：讓路徑覆蓋、任務協議、狀態映射、錯誤解析和結果解析更容易配置和復用。 -- **治理審計與營運優化**：完善請求鏈路、成本追蹤、錯誤分析、管理員審計、日志留存和運維報表。 -- **組織級營運能力**：增強多租戶、分組、賬單、權限、風控和私有化部署體驗。 +| 能力 | 主要用途 | +|---|---| +| 統一模型入口 | 接入 OpenAI Compatible、Responses、Claude Messages、Gemini、Realtime 和多模態任務介面 | +| 多供應商路由 | 管理渠道、權重、優先級、分組、模型映射、失敗重試和跨供應商切換 | +| 身分與存取控制 | 管理使用者、權杖、模型範圍、分組、額度、有效期、限流和管理員權限 | +| 成本與計費 | 支援倍率、固定價格、表達式計費、非同步任務 rate-card、預扣費、結算和失敗退款 | +| 日誌與稽核 | 按使用者、權杖、模型、渠道、分組和節點查看使用、錯誤、重試和管理操作 | +| 智慧運維中心 | 集中查看活動告警、渠道效能、模型效能、系統資訊和計費結算對帳證據，協助管理員發現、定位和審閱生產問題 | +| 私有化部署 | 支援 SQLite、MySQL、PostgreSQL、Redis、多節點和獨立日誌庫 | +| 上游擴充 | 支援協定適配、路徑覆寫、參數/Header 覆寫、模型發現和任務狀態映射 | -歡迎在 [GitHub Issues](https://github.com/MAX-API-Next/MAX-API/issues) 提出需求、問題和改進建議。 +### 適用場景 ---- +- **團隊或組織內部模型閘道**：統一管理使用者、權杖、模型、供應商、權限和費用。 +- **AI 應用與 Agent 運行底座**：為應用、Agent 和工作流程提供模型存取控制、成本歸因與異常定位。 +- **多供應商容錯與遷移**：透過模型映射、加權路由、失敗重試和灰度切換降低單一上游風險。 +- **多模態任務治理**：統一管理圖像、音訊、影片、嵌入、重排序和即時對話介面。 +- **私有化與合規營運**：自主管理金鑰、資料、日誌、稽核、價格和部署環境。 -## ❓ 常見問題 +## 🩺 智慧運維中心 -
-MAX API 會提供模型服務或 API Key 嗎？ +**智慧運維中心是 MAX API 2.0 的重大更新，也是專案從統一模型閘道走向 AGI 原生治理與營運基礎設施的關鍵一步。** -不會。MAX API 是模型與 Agent 工作負載的網關治理層，不提供上游模型賬號、API Key、基礎模型訓練能力或模型服務本身。使用者需要自行獲得合法授權的上游服務。 +它將生產觀測、資源告警、模型與渠道效能、系統資訊和計費結算對帳集中到統一管理員入口。目前能力強調「看見問題、保留證據、通知管理員、受控審閱」，並不是會自動修改渠道、路由、餘額或主機的自治 Agent。 -
- -
-MAX API 和 Agent 框架是什么關系？ +| 模組 | 目前提供的內容 | +|---|---| +| 活動告警 | 對目前節點的 CPU、記憶體和磁碟持續超閾值進行去重告警，在復原時傳送復原通知；沿用管理員既有的 Email、Webhook、Bark 或 Gotify 設定 | +| 渠道效能 | 查看請求與錯誤、消耗額度、估算成功率、日誌延遲、重試、探測延遲和最近觀測時間；詳細資訊可查看該渠道最近 24 小時的模型與分組表現 | +| 模型效能 | 彙總所有模型的渠道數、請求與錯誤、消耗額度、估算成功率、日誌延遲、吞吐量和重試；詳細資訊提供各分組效能、延遲趨勢和可用率趨勢 | +| 計費結算對帳 | 顯示 `pending` / `manual` 正向最終結算、未結資金、重試和錯誤證據；根管理員可設定預設使用者阻斷策略，管理員可按 `id + revision` 原子批次審閱並關閉告警 | +| 系統資訊 | 查看節點、執行個體和系統任務等資訊；此模組仍要求超級管理員權限 | -MAX API 不替代 Dify、LangChain、MCP Server、工作流引擎或業務 Agent 應用。它位于這些應用與上游模型服務之間，負責模型接入、令牌隔離、成本核算、路由容災、日志觀測和管理員審計等治理能力。 - -
- -
-為什麼強調 AI 模型治理？ +活動告警頁面每 5 秒讀取一次目前告警狀態，但不會觸發新的檢測或修復動作。渠道與模型清單預設查詢最近 1 小時，管理員可以輸入 `1–168` 小時的自訂時間窗；它們不會自動反覆統計大型日誌庫，只有按一下「套用篩選」或「重新整理」時才執行查詢，詳細資料在開啟時按需載入。 -在真實組織中，模型不只是一個 API 名稱，還涉及供應商、價格、上下文長度、協議格式、權限范圍、穩定性和審計邊界。MAX API 的價值在于把這些分散變量統一配置、統一觀察和統一核算。 +計費結算對帳將財務復原狀態與運維告警狀態嚴格分離：「審閱並關閉」只會記錄管理員審閱並關閉目前告警，不會將結算標記為 `applied`，不會修改餘額、已套用差額或 effect 狀態。批次審閱綁定目前財務 revision；重新整理後記錄發生變化時，舊選擇會自動失效，避免使用過期證據進行操作。 -
- -
-支持哪些資料庫？ - -支持 SQLite、MySQL ≥ 5.7.8 和 PostgreSQL ≥ 9.6。本地體驗可使用 SQLite；生產環境建議使用 MySQL 或 PostgreSQL，并做好備份。 - -
- -
-能否從 New API / One API 遷移？ - -專案兼容 New API 與原版 One API 的主要資料結構，通常可以復用既有資料。遷移前仍建議備份資料庫，并在測試環境驗證渠道、倍率、使用者、令牌和日志資料。 +> [!NOTE] +> 目前生產效能主要彙總既有 Consume/Error 日誌和 `perf_metrics`：估算成功率並非完整的 Relay Attempt 成功率，吞吐量與趨勢屬於效能桶級近似值。日誌關閉、歷史資料缺失、採集關閉、時間窗無樣本或查詢失敗時，頁面會顯示相應的資料品質狀態。 +> +> 活動告警依賴效能監控和資源閾值設定；閾值設為 `0` 時代表關閉該資源告警，需要連續兩個有效樣本才會觸發。狀態與通知佇列只保存在目前處理程序記憶體中：處理程序重新啟動後不會保留，多節點也不會自動合併為跨節點 Incident。渠道、模型和系統觀測保持唯讀；結算審閱只更新審閱中繼資料與使用者阻斷策略，不執行資金結算。智慧運維中心不會自動測試、停用、調權、切換渠道或修復主機。 -
+此階段的價值，是先完成「看見問題、通知管理員、提供證據、受控審閱」的閉環，為後續統一 Evidence、診斷 Agent、Evaluator 和受控自動化建立基礎。 -
-多機部署需要注意什么？ +## 🔌 模型、介面與擴充 -必須統一 `SESSION_SECRET`。如果使用共享 Redis，也必須統一 `CRYPTO_SECRET`。否則可能出現登錄狀態不一致、緩存資料無法解密或任務狀態異常。 +> 實際可用能力取決於你的上游授權、渠道設定、模型映射和供應商支援。MAX API 負責治理這些能力，不提供模型服務本身。 -
+| 類別 | 介面或能力 | +|---|---| +| 通用模型介面 | Chat Completions、Responses、Embeddings、Rerank、Images、Audio、Video | +| 原生與即時協定 | Claude Messages、Google Gemini、OpenAI Realtime 等入口 | +| 推理與工具呼叫 | 支援 Reasoning Effort、函式工具、Tool Call ID、工具名稱和多輪工具回應關聯，並依不同上游能力進行協定轉換 | +| 非同步任務 | 任務提交、輪詢、狀態映射、結果代理和參數化計費 | +| 自訂上游 | Base URL、路徑、參數、Header、狀態欄位和結果欄位映射 | -
-圖像生成、流式響應或大響應被截斷怎么辦？ +涵蓋 OpenAI、Claude、Gemini、Azure、AWS Bedrock、Vertex AI、Ollama 及多種中國模型平台，也可治理 Codex、Dify、RAGFlow 和多模態任務服務。具體支援範圍以目前版本和渠道類型為準。 -可調大 `STREAM_SCANNER_MAX_BUFFER_MB`。4K 圖像、base64 圖片、長流式響應等場景可能需要更大的掃描緩沖。 +### 系統運作方式與技術堆疊 -
+![MAX API 系統架構圖](./docs/images/MAX-API架构图.png) -
-請求體過大返回 413 怎么辦？ +```text +應用 / SDK / Agent + → 統一介面與身分鑑權 + → 模型權限、限流、預算和安全檢查 + → 渠道選擇、映射與失敗重試 + → 上游協定適配 + → 可復原結算、Evidence、日誌和稽核 + → 智慧運維中心與管理員治理 +``` -調整 `MAX_REQUEST_BODY_MB`。該限制按解壓后的請求體大小計算，用于防止超大請求或 zip bomb 導致內存暴漲。 +後端使用 Go、Gin 和 GORM，前端使用 React 19、TypeScript、Base UI 與 Tailwind CSS，資料層相容 SQLite、MySQL 和 PostgreSQL，並可使用 Redis 與獨立日誌庫。供應商協定適配位於獨立 Relay/Channel 層，計費與結算集中在統一服務邊界中，管理端透過 SmartOps 顯示唯讀觀測和受限治理入口。 -
+## 🛡️ 治理與營運 -
-使用者能看到管理員日志審計中的輸入輸出內容嗎？ +生產環境建議依以下順序設定： -正常使用者日志介面會過濾管理員專用字段，普通使用者無法在自助使用日志中看到管理員審計內容。資料庫管理員、系統管理員或擁有管理員日志介面權限的人仍可能訪問相關資料，因此應按合規要求嚴格控制權限。 +1. 設定登入、安全限制和使用者註冊策略。 +2. 新增合法授權的上游渠道，確認模型、能力和協定設定。 +3. 按團隊、業務或環境設定分組、權杖、模型範圍、額度和價格。 +4. 為每個應用、Agent 或環境使用獨立權杖，避免共用憑證和成本歸屬。 +5. 設定重試、日誌與告警，透過資料看板和智慧運維中心持續觀察。 -
+渠道能力驗證、表達式計費、通用任務協定、管理員稽核和效能參數等進階設定，請查看[詳細文件](https://docs.max-api.ai)。 -
-為什麼 Docker 構建時提示 `catalog:` 依賴無法解析？ +## 🧭 演進路線 -前端使用 Bun workspace，`catalog:` 依賴定義在 `web/package.json`。構建時不能用 `web/default/package.json` 覆蓋 workspace 根 `package.json`，并且需要保留 `web/bun.lock`。 +MAX API 將繼續以 **AI Models and Agents governance** 為核心，從統一閘道、智慧運維和可復原結算出發，逐步建設面向 AGI 應用的 Evidence、評測、策略與受控執行能力。長期方向不是讓一個無邊界 Agent 接管生產系統，而是建立可驗證、可審批、可停止、可回復的工程閉環。 -
+| 階段 | 狀態 | 重點 | +|---|---|---| +| 統一閘道與智慧運維 | **目前已提供** | 接入、鑑權、路由、計費、日誌、資源告警、渠道/模型效能、系統資訊和計費結算對帳 | +| Evidence 事實層 | **近期建設** | 統一模型請求、系統日誌、指標、Task、路由、策略、結算和稽核事件，向 Agent 提供脫敏、限權、唯讀介面 | +| 開放評測與治理範本 | **規劃中** | 與社群沉澱模型/協定相容測試、匿名故障樣本、評測集、Runbook、Detector 和產業治理範本 | +| 受控自治運維 | **長期藍圖** | 在 Policy、Budget、Approval、Shadow、Canary 和 Rollback 約束下評估低風險自動動作 | +| 受控能力進化 | **長期藍圖** | 在隔離 Coding Workspace 中生成、測試和審閱候選改進，不直接修改生產系統 | +| AGI 工程閉環 | **長期方向** | 將 Evidence、評測、治理策略、人工審批與可回復執行連接為可驗證閉環 | ---- +MAX API 不是基礎模型，也不宣稱目前已經實現 AGI 或自治運維。路線圖中的長期能力只有在證據、權限、預算、審批和回復邊界完善後才會逐步驗證。 -## 🔗 相關專案 +## 🚢 Preview 部署 -| 專案 | 說明 | -|------|------| -| [One API](https://github.com/songquanpeng/one-api) | MIT 協議 | -| [New API](https://github.com/QuantumNous/new-api) | AGPLv3 協議 | -| [Midjourney-Proxy](https://github.com/novicezk/midjourney-proxy) | Apache-2.0 協議 | -| [Suno API](https://github.com/Suno-API/Suno-API) | MIT 協議 | +以下步驟用於 Preview 版本的測試和灰度驗證。生產環境請改用正式版，並沿用相同的驗證和回復流程。 -### 配套工具 +建議使用 Docker Compose： -| 專案 | 說明 | -|------|------| -| [max-api-key-tool](https://github.com/MAX-API-Next/MAX-API-key-tool) | Key 額度查詢工具 | -| [max-api-horizon](https://github.com/MAX-API-Next/MAX-API-horizon) | MAX API 高性能優化版 | +```bash +MAX_API_VERSION=v2.0.0-smartops.pre1 +MAX_API_COMMIT=b7096156549edc930ca244891afb1ba5632dbe8f +git clone --branch "$MAX_API_VERSION" --depth 1 https://github.com/MAX-API-Next/MAX-API.git +cd MAX-API ---- +actual_commit="$(git rev-parse HEAD)" +if [ "$actual_commit" != "$MAX_API_COMMIT" ]; then + echo "Unexpected commit: $actual_commit" >&2 + exit 1 +fi -## 📚 文檔與支持 - -| 資源 | 鏈接 | -|------|------| -| 官方文檔 | [MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) | -| 問題反饋 | [GitHub Issues](https://github.com/MAX-API-Next/MAX-API/issues) | -| 最新發布 | [Releases](https://github.com/MAX-API-Next/MAX-API/releases) | -| DeepWiki | [Ask DeepWiki](https://deepwiki.com/MAX-API-Next/MAX-API) | - -### 二次開發與社群鳴謝 - -如果你基於本專案進行二次開發且僅供自用，歡迎在專案首頁、頁尾或「關於」頁面等明顯位置，任選一種方式保留專案來源或社群鳴謝： - -- 加入專案網址：[MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) -- 鳴謝社群：[MAX-API-Next](https://github.com/MAX-API-Next) - -參考前端嵌入程式碼（React / Tailwind CSS，可按需保留其中一項）： - -```tsx -

- 基於{' '} - - MAX-API-Next/MAX-API - {' '} - 二次開發 · 感謝{' '} - - MAX-API-Next 社群 - -

+# 修改 docker-compose.yml 中的資料庫、Redis 密碼和金鑰 +docker compose up -d ``` -滿足上述任一展示要求並保持連結清晰可見，即自動獲得本專案的臨時商用授權，無需另行申請或等待確認。該授權為非永久授權，僅在持續滿足展示要求期間有效；有效期及後續調整以專案方在本 README 或官方社群發布的最新說明為準。 +### 部署檢查 -本專案基於 [One API](https://github.com/songquanpeng/one-api) 和 [New API](https://github.com/QuantumNous/new-api) 開發。現階段，MAX API 主要在上述專案基礎上持續強化 AI API 閘道與治理能力、擴充功能並修正問題。商業使用本專案時，還須分別遵守 One API 的 MIT 許可證與 New API 的 AGPLv3 許可證，具體以各上游專案的 `LICENSE` 檔案為準；本專案提供的臨時商用授權不替代、也不免除相關上游專案的開源許可義務。 +| 元件 | 建議 | +|---|---| +| 資料庫 | 使用仍在供應商安全支援週期內的 MySQL（建議 8.4 LTS）或 PostgreSQL（建議 14+），並設定備份與復原 | +| 快取 | 單機可使用記憶體快取，多節點部署建議使用 Redis | +| 入口 | 設定 HTTPS 反向代理、請求大小限制和可信任網路策略 | +| 金鑰 | 明確設定隨機 `SESSION_SECRET`；`CRYPTO_SECRET` 為可選覆寫項，未設定時回退到 `SESSION_SECRET`，如單獨設定則需在 Redis/多節點場景統一 | +| 節點 | 每個節點設定穩定且唯一的 `NODE_NAME` | +| 日誌 | 依合規和運維需要設定 `LOG_SQL_DSN`、清理與保留策略 | -如不再滿足展示要求，或臨時授權到期、被公告調整或終止，仍需按 AGPLv3 或專案方另行書面授權使用本專案。如需長期商用授權，請聯絡：maxapi@max-api.ai。 +多節點必須統一 `SESSION_SECRET`，並為每個節點使用不同的 `NODE_NAME`。`CRYPTO_SECRET` 為可選覆寫項，未設定時使用 `SESSION_SECRET`；如明確設定，所有節點必須使用相同值。獨立日誌庫使用 `LOG_SQL_DSN`；錯誤效能統計需要按需啟用 `ERROR_LOG_ENABLED`。完整環境變數和原始碼建置說明請見[詳細文件](https://docs.max-api.ai)。 -歡迎提交 Issue、改進文檔、補充供應商適配經驗、完善部署方案或貢獻代碼。 +## 🤝 專案來源、致謝與二次開發 ---- +MAX API 基於 [One API](https://github.com/songquanpeng/one-api) 和 [New API](https://github.com/QuantumNous/new-api) 的開源成果持續開發。感謝上游專案、貢獻者，以及所有參與協定適配、測試、文件、翻譯與問題回報的社群成員。 -## 📜 許可證 +根據 [NOTICE](./NOTICE) 與 AGPLv3 第 7 節，包含使用者介面的修改版本必須在清楚可見的「關於」、法律聲明、頁尾或署名位置同時保留： -本專案采用 [GNU Affero 通用公共許可證 v3.0 (AGPLv3)](./LICENSE) 授權。 +- MAX API 原專案連結：[MAX-API-Next/MAX-API](https://github.com/MAX-API-Next/MAX-API) +- MAX API NOTICE 中的原文署名：`Frontend design and development by MAX API contributors.` +- New API 上游專案連結：[QuantumNous/new-api](https://github.com/QuantumNous/new-api) +- New API NOTICE 中的原文署名：`Frontend design and development by New API contributors.` +- 明確的修改聲明及相關修改日期 -除預設的 AGPLv3 授權外，符合上文「二次開發與社群鳴謝」條件的自用二開專案，可按該說明自動獲得非永久的臨時商用授權。該臨時授權僅涵蓋 MAX API 專案方有權授權的新增與修改部分，並不包含或代替 One API、New API 等上游專案的許可授權。 +可以額外鳴謝 [MAX-API-Next 社群](https://github.com/MAX-API-Next)，但社群鳴謝不能取代上述必要的專案連結、原文署名和變更標記。 -如果你修改并通過網絡向使用者提供本專案服務，請理解并遵守 AGPLv3 對應源碼提供等義務。商業合作、機構合作或其他授權問題，請聯系：maxapi@max-api.ai。 +持續滿足上述展示與 NOTICE 要求，即自動取得本專案的非永久臨時商用授權，無需另外申請或等待確認；該授權僅涵蓋 MAX API 專案方有權授權的部分，不免除 AGPLv3 或 One API、New API 等上游專案的許可義務。最新條件以正式 README 與官方社群公告為準。 ---- - -## 🌟 Star History +## 📜 許可證 -
+本專案採用 [GNU Affero 通用公共許可證 v3.0（AGPLv3）](./LICENSE) 授權。 -[![Star History Chart](https://api.star-history.com/svg?repos=MAX-API-Next/MAX-API&type=Date)](https://star-history.com/#MAX-API-Next/MAX-API&Date) +臨時商用授權僅涵蓋 MAX API 專案方有權授權的新增與修改部分，不包含、取代或免除 One API、New API 等上游專案的許可義務。商業使用時，請同時遵守 One API 的 MIT 許可證、New API 的 AGPLv3 許可證及各上游專案的最新許可要求。 -
+如果你修改並透過網路向使用者提供本專案服務，請理解並遵守 AGPLv3 對應的原始碼提供等義務。長期商用授權、機構合作或其他授權問題，請聯絡：maxapi@max-api.ai。 --- @@ -767,9 +356,9 @@ MAX API 不替代 Dify、LangChain、MCP Server、工作流引擎或業務 Agent ### 💖 感謝使用 MAX API -如果這個專案對你有幫助，歡迎給我們一個 ⭐ Star。 +如果這個專案對你有幫助，歡迎給我們一個 ⭐ Star、關注 Releases、提交可重現 Issue，或參與 MAX-API-Next 社群共建。 -**[官方文檔](https://github.com/MAX-API-Next/MAX-API)** • **[問題反饋](https://github.com/MAX-API-Next/MAX-API/issues)** • **[最新發布](https://github.com/MAX-API-Next/MAX-API/releases)** +**[專案倉庫](https://github.com/MAX-API-Next/MAX-API)** • **[參與共建](https://github.com/MAX-API-Next/MAX-API/issues)** • **[最新發布](https://github.com/MAX-API-Next/MAX-API/releases)** • **[MAX-API-Next 社群](https://github.com/MAX-API-Next)** Built with ❤️ by MAX-API-Next diff --git a/docker-compose.yml b/docker-compose.yml index 05abd152..40adf711 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -16,12 +16,12 @@ version: '3.4' # For compatibility with older Docker versions services: max-api: - image: cscitechtop/max-api:latest + image: cscitechtop/max-api:latest@sha256:006d5d86887a261baab4d71ec3797d429e3771a4836e5899734aee0e7f66f2ab container_name: max-api restart: always command: --log-dir /app/logs ports: - - "3000:3000" + - "127.0.0.1:3000:3000" volumes: - ./data:/data - ./logs:/app/logs diff --git "a/docs/images/MAX-API\346\236\266\346\236\204\345\233\276.png" "b/docs/images/MAX-API\346\236\266\346\236\204\345\233\276.png" index 56dfd547..38e5dc51 100644 Binary files "a/docs/images/MAX-API\346\236\266\346\236\204\345\233\276.png" and "b/docs/images/MAX-API\346\236\266\346\236\204\345\233\276.png" differ diff --git a/docs/images/aionui.png b/docs/images/aionui.png deleted file mode 100644 index f708588c..00000000 Binary files a/docs/images/aionui.png and /dev/null differ diff --git a/docs/images/aliyun.png b/docs/images/aliyun.png deleted file mode 100644 index 6266bfbf..00000000 Binary files a/docs/images/aliyun.png and /dev/null differ diff --git a/docs/images/cherry-studio.png b/docs/images/cherry-studio.png deleted file mode 100644 index a58a7713..00000000 Binary files a/docs/images/cherry-studio.png and /dev/null differ diff --git a/docs/images/io-net.png b/docs/images/io-net.png deleted file mode 100644 index fb47534d..00000000 Binary files a/docs/images/io-net.png and /dev/null differ diff --git a/docs/images/pku.png b/docs/images/pku.png deleted file mode 100644 index a058c3ce..00000000 Binary files a/docs/images/pku.png and /dev/null differ diff --git a/docs/images/ucloud.png b/docs/images/ucloud.png deleted file mode 100644 index 16cca764..00000000 Binary files a/docs/images/ucloud.png and /dev/null differ diff --git a/docs/installation/BT.md b/docs/installation/BT.md index 8ba1c435..bee1b2d2 100644 --- a/docs/installation/BT.md +++ b/docs/installation/BT.md @@ -41,12 +41,12 @@ 3. 点击 **安装** 4. 配置以下基本选项： - **容器名称**：可自定义，默认为 `max-api` - - **端口映射**：默认为 `3000:3000` + - **端口映射**：设置为 `127.0.0.1:3000:3000`，仅允许服务器本机和反向代理访问 - **环境变量**： - `SESSION_SECRET`：会话密钥（**必填**，多机部署时必须一致） - - `CRYPTO_SECRET`：加密密钥（使用 Redis 时必填） + - `CRYPTO_SECRET`：可选的加密密钥覆盖项；未设置时回退使用 `SESSION_SECRET`，如单独设置则多机/Redis 节点必须一致 5. 点击 **确认** 开始安装 -6. 等待安装完成后，访问 `http://您的服务器IP:3000` 即可使用 +6. 等待安装完成后，为站点配置 HTTPS 反向代理，再通过 `https://您的域名` 登录；`http://127.0.0.1:3000` 仅用于服务器本机检查，不应直接暴露到公网 ### 方法二：使用 Docker Compose @@ -57,11 +57,11 @@ version: '3' services: max-api: - image: cscitechtop/max-api:latest + image: cscitechtop/max-api:latest@sha256:006d5d86887a261baab4d71ec3797d429e3771a4836e5899734aee0e7f66f2ab container_name: max-api restart: always ports: - - "3000:3000" + - "127.0.0.1:3000:3000" volumes: - ./data:/data environment: @@ -85,7 +85,7 @@ docker-compose up -d | 变量名 | 说明 | 是否必填 | | ------------------- | ------------------ | ------ | | `SESSION_SECRET` | 会话密钥，多机部署必须一致 | **必填** | -| `CRYPTO_SECRET` | 加密密钥，使用 Redis 时必填 | 条件必填 | +| `CRYPTO_SECRET` | 可选的加密密钥覆盖项；未设置时回退使用 `SESSION_SECRET`，显式设置时多机/Redis 节点需一致 | 可选 | | `SQL_DSN` | 数据库连接字符串（使用外部数据库时） | 可选 | | `REDIS_CONN_STRING` | Redis 连接字符串 | 可选 | @@ -103,11 +103,11 @@ head -c 16 /dev/urandom | xxd -p ## 常见问题 -### Q1：无法访问 3000 端口？ +### Q1：无法通过 HTTPS 域名访问？ -1. 检查服务器防火墙是否开放 3000 端口 -2. 在宝塔面板 **安全** 中放行 3000 端口 -3. 检查云服务器安全组是否开放端口 +1. 在服务器本机执行 `curl http://127.0.0.1:3000`，确认 MAX API 容器正常响应 +2. 检查宝塔站点的 HTTPS 反向代理目标是否为 `http://127.0.0.1:3000` +3. 检查域名解析、TLS 证书和 443 端口；不要在防火墙或云安全组中向公网开放 3000 端口 ### Q2：登录后提示会话失效？ @@ -125,8 +125,8 @@ volumes: ### Q4：如何更新版本？ ```bash -# 拉取最新镜像 -docker pull cscitechtop/max-api:latest +# 拉取经过校验的固定镜像 +docker pull cscitechtop/max-api:latest@sha256:006d5d86887a261baab4d71ec3797d429e3771a4836e5899734aee0e7f66f2ab # 重启容器 docker-compose down && docker-compose up -d @@ -148,4 +148,3 @@ docker-compose down && docker-compose up -d ![宝塔面板 Docker 安装](https://github.com/user-attachments/assets/7a6fc03e-c457-45e4-b8f9-184508fc26b0) > ⚠️ 注意：密钥为环境变量 `SESSION_SECRET`，请务必设置！ - diff --git a/web/default/src/components/data-table/toolbar.tsx b/web/default/src/components/data-table/toolbar.tsx index 9fa2cdfe..dc04c2f3 100644 --- a/web/default/src/components/data-table/toolbar.tsx +++ b/web/default/src/components/data-table/toolbar.tsx @@ -97,6 +97,14 @@ export type DataTableToolbarProps = { * (form-mode workflow). */ onSearch?: () => void + /** + * Controlled value for a submit-mode global search input. When provided, + * typing updates this value without changing the table filter until + * {@link onSearch} is invoked. + */ + searchValue?: string + /** Change handler for a controlled submit-mode global search input. */ + onSearchValueChange?: (value: string) => void /** * Loading state for the explicit Search button. */ @@ -144,12 +152,14 @@ export function DataTableToolbar(props: DataTableToolbarProps) { const isFiltered = props.table.getState().columnFilters.length > 0 || !!props.table.getState().globalFilter || + !!props.searchValue?.trim() || !!props.hasAdditionalFilters const placeholder = props.searchPlaceholder ?? t('Filter...') const searchInput = props.searchKey ? ( (props: DataTableToolbarProps) { /> ) : ( props.table.setGlobalFilter(event.target.value)} + value={props.searchValue ?? props.table.getState().globalFilter ?? ''} + onChange={(event) => { + const value = event.target.value + if (props.onSearchValueChange) { + props.onSearchValueChange(value) + } else { + props.table.setGlobalFilter(value) + } + }} + onKeyDown={(event) => { + if ( + event.key === 'Enter' && + !event.nativeEvent.isComposing && + props.onSearch + ) { + event.preventDefault() + props.onSearch() + } + }} className='w-full sm:w-[200px] lg:w-[240px]' /> ) @@ -187,7 +215,11 @@ export function DataTableToolbar(props: DataTableToolbarProps) { const handleReset = () => { props.table.resetColumnFilters() - props.table.setGlobalFilter('') + if (props.onSearchValueChange) { + props.onSearchValueChange('') + } else { + props.table.setGlobalFilter('') + } props.onReset?.() } diff --git a/web/default/src/features/channels/components/channels-table.tsx b/web/default/src/features/channels/components/channels-table.tsx index 97fb544b..ab4893b1 100644 --- a/web/default/src/features/channels/components/channels-table.tsx +++ b/web/default/src/features/channels/components/channels-table.tsx @@ -16,13 +16,7 @@ along with this program. If not, see . For commercial licensing, please contact https://github.com/MAX-API-Next/MAX-API/issues */ -import { - useState, - useMemo, - useEffect, - useRef, - type CompositionEvent, -} from 'react' +import { useState, useMemo, useEffect } from 'react' import { useQuery } from '@tanstack/react-query' import { getRouteApi } from '@tanstack/react-router' import { @@ -35,7 +29,7 @@ import { type ExpandedState, type Row, } from '@tanstack/react-table' -import { useDebounce, useMediaQuery } from '@/hooks' +import { useMediaQuery } from '@/hooks' import { useTranslation } from 'react-i18next' import { getLobeIcon } from '@/lib/lobe-icon' import { useTableUrlState } from '@/hooks/use-table-url-state' @@ -98,6 +92,10 @@ export function ChannelsTable() { const { globalFilter, onGlobalFilterChange, + globalFilterInput, + onGlobalFilterInputChange, + applyGlobalFilter, + resetGlobalFilter, columnFilters, onColumnFiltersChange, pagination, @@ -110,7 +108,7 @@ export function ChannelsTable() { defaultPage: 1, defaultPageSize: isMobile ? 10 : DEFAULT_PAGE_SIZE, }, - globalFilter: { enabled: true, key: 'filter' }, + globalFilter: { enabled: true, key: 'filter', mode: 'submit' }, columnFilters: [ { columnId: 'status', searchKey: 'status', type: 'array' }, { columnId: 'type', searchKey: 'type', type: 'array' }, @@ -122,60 +120,37 @@ export function ChannelsTable() { // Extract filters from column filters const statusFilter = (columnFilters.find((f) => f.id === 'status')?.value as string[]) || [] - const typeFilter = - (columnFilters.find((f) => f.id === 'type')?.value as string[]) || [] + const typeFilter = useMemo( + () => (columnFilters.find((f) => f.id === 'type')?.value as string[]) || [], + [columnFilters] + ) const groupFilter = (columnFilters.find((f) => f.id === 'group')?.value as string[]) || [] const modelFilterFromUrl = (columnFilters.find((f) => f.id === 'model')?.value as string) || '' - // Local state for immediate input feedback + // Keep the model filter local until the toolbar Search action is submitted. const [modelFilterInput, setModelFilterInput] = useState(modelFilterFromUrl) - const [pendingModelFilter, setPendingModelFilter] = - useState(modelFilterFromUrl) - const isModelFilterComposingRef = useRef(false) - const debouncedModelFilter = useDebounce(pendingModelFilter, 500) // Sync local input with URL when URL changes (e.g., from back/forward navigation) useEffect(() => { - if (!isModelFilterComposingRef.current) { - setModelFilterInput(modelFilterFromUrl) - } - setPendingModelFilter(modelFilterFromUrl) + setModelFilterInput(modelFilterFromUrl) }, [modelFilterFromUrl]) - const handleModelFilterChange = (value: string) => { + const handleModelFilterChange = (value: string): void => { setModelFilterInput(value) - if (!isModelFilterComposingRef.current) { - setPendingModelFilter(value) - } } - const handleModelFilterCompositionStart = () => { - isModelFilterComposingRef.current = true + const handleSearch = (): void => { + const modelFilter = modelFilterInput.trim() + applyGlobalFilter?.({ model: modelFilter || undefined }) } - const handleModelFilterCompositionEnd = ( - event: CompositionEvent - ) => { - isModelFilterComposingRef.current = false - const value = event.currentTarget.value - setModelFilterInput(value) - setPendingModelFilter(value) + const handleReset = (): void => { + setModelFilterInput('') + resetGlobalFilter?.({ model: undefined }) } - // Update URL when debounced value changes - useEffect(() => { - if (debouncedModelFilter !== modelFilterFromUrl) { - onColumnFiltersChange((prev) => { - const filtered = prev.filter((f) => f.id !== 'model') - return debouncedModelFilter - ? [...filtered, { id: 'model', value: debouncedModelFilter }] - : filtered - }) - } - }, [debouncedModelFilter, modelFilterFromUrl, onColumnFiltersChange]) - const modelFilter = modelFilterFromUrl // Determine whether to use search or regular list API @@ -417,13 +392,24 @@ export function ChannelsTable() { applyHeaderSize toolbarProps={{ searchPlaceholder: t('Filter by name, ID, or key...'), + onSearch: handleSearch, + searchValue: globalFilterInput, + onSearchValueChange: onGlobalFilterInputChange, + onReset: handleReset, + hasAdditionalFilters: Boolean(modelFilterInput.trim()), + searchLoading: isFetching, additionalSearch: ( handleModelFilterChange(e.target.value)} - onCompositionStart={handleModelFilterCompositionStart} - onCompositionEnd={handleModelFilterCompositionEnd} + onKeyDown={(event) => { + if (event.key === 'Enter' && !event.nativeEvent.isComposing) { + event.preventDefault() + handleSearch() + } + }} className='w-full sm:w-[150px] lg:w-[180px]' /> ), diff --git a/web/default/src/features/keys/components/api-keys-table.tsx b/web/default/src/features/keys/components/api-keys-table.tsx index ceef197b..229b897e 100644 --- a/web/default/src/features/keys/components/api-keys-table.tsx +++ b/web/default/src/features/keys/components/api-keys-table.tsx @@ -30,7 +30,6 @@ import { getSortedRowModel, useReactTable, } from '@tanstack/react-table' -import { useDebounce } from '@/hooks' import { Database } from 'lucide-react' import { useTranslation } from 'react-i18next' import { toast } from 'sonner' @@ -199,6 +198,10 @@ export function ApiKeysTable() { const { globalFilter, onGlobalFilterChange, + globalFilterInput, + onGlobalFilterInputChange, + applyGlobalFilter, + resetGlobalFilter, columnFilters, onColumnFiltersChange, pagination, @@ -208,7 +211,7 @@ export function ApiKeysTable() { search: route.useSearch(), navigate: route.useNavigate(), pagination: { defaultPage: 1, defaultPageSize: 20 }, - globalFilter: { enabled: true, key: 'filter' }, + globalFilter: { enabled: true, key: 'filter', mode: 'submit' }, columnFilters: [ { columnId: 'status', searchKey: 'status', type: 'array' }, { columnId: '_tokenSearch', searchKey: 'token', type: 'string' }, @@ -218,22 +221,20 @@ export function ApiKeysTable() { const tokenFilterFromUrl = (columnFilters.find((f) => f.id === '_tokenSearch')?.value as string) || '' const [tokenFilterInput, setTokenFilterInput] = useState(tokenFilterFromUrl) - const debouncedTokenFilter = useDebounce(tokenFilterInput, 500) useEffect(() => { setTokenFilterInput(tokenFilterFromUrl) }, [tokenFilterFromUrl]) - useEffect(() => { - if (debouncedTokenFilter !== tokenFilterFromUrl) { - onColumnFiltersChange((prev) => { - const filtered = prev.filter((f) => f.id !== '_tokenSearch') - return debouncedTokenFilter - ? [...filtered, { id: '_tokenSearch', value: debouncedTokenFilter }] - : filtered - }) - } - }, [debouncedTokenFilter, tokenFilterFromUrl, onColumnFiltersChange]) + const handleSearch = (): void => { + const tokenFilter = tokenFilterInput.trim() + applyGlobalFilter?.({ token: tokenFilter || undefined }) + } + + const handleReset = (): void => { + setTokenFilterInput('') + resetGlobalFilter?.({ token: undefined }) + } const tokenFilter = tokenFilterFromUrl const shouldSearch = Boolean(globalFilter?.trim() || tokenFilter.trim()) @@ -331,12 +332,24 @@ export function ApiKeysTable() { skeletonKeyPrefix='api-keys-skeleton' toolbarProps={{ searchPlaceholder: t('Filter by name...'), + onSearch: handleSearch, + searchValue: globalFilterInput, + onSearchValueChange: onGlobalFilterInputChange, + onReset: handleReset, + hasAdditionalFilters: Boolean(tokenFilterInput.trim()), + searchLoading: isFetching, additionalSearch: ( setTokenFilterInput(e.target.value)} + onKeyDown={(event) => { + if (event.key === 'Enter' && !event.nativeEvent.isComposing) { + event.preventDefault() + handleSearch() + } + }} className='w-full sm:w-50 lg:w-60' /> ), diff --git a/web/default/src/features/models/components/deployments-table.tsx b/web/default/src/features/models/components/deployments-table.tsx index 15043273..3e011f4c 100644 --- a/web/default/src/features/models/components/deployments-table.tsx +++ b/web/default/src/features/models/components/deployments-table.tsx @@ -61,6 +61,10 @@ export function DeploymentsTable() { const { globalFilter, onGlobalFilterChange, + globalFilterInput, + onGlobalFilterInputChange, + applyGlobalFilter, + resetGlobalFilter, columnFilters, onColumnFiltersChange, pagination, @@ -75,7 +79,7 @@ export function DeploymentsTable() { defaultPage: 1, defaultPageSize: isMobile ? 8 : 10, }, - globalFilter: { enabled: true, key: 'dFilter' }, + globalFilter: { enabled: true, key: 'dFilter', mode: 'submit' }, columnFilters: [ { columnId: 'status', searchKey: 'dStatus', type: 'array' }, ], @@ -243,6 +247,11 @@ export function DeploymentsTable() { applyHeaderSize toolbarProps={{ searchPlaceholder: t('Search deployments...'), + onSearch: applyGlobalFilter, + searchValue: globalFilterInput, + onSearchValueChange: onGlobalFilterInputChange, + onReset: resetGlobalFilter, + searchLoading: isFetching, filters: [ { columnId: 'status', diff --git a/web/default/src/features/models/components/models-table.tsx b/web/default/src/features/models/components/models-table.tsx index 155af5e2..7cc96bbb 100644 --- a/web/default/src/features/models/components/models-table.tsx +++ b/web/default/src/features/models/components/models-table.tsx @@ -60,6 +60,10 @@ export function ModelsTable() { const { globalFilter, onGlobalFilterChange, + globalFilterInput, + onGlobalFilterInputChange, + applyGlobalFilter, + resetGlobalFilter, columnFilters, onColumnFiltersChange, pagination, @@ -72,7 +76,7 @@ export function ModelsTable() { defaultPage: 1, defaultPageSize: isMobile ? 10 : DEFAULT_PAGE_SIZE, }, - globalFilter: { enabled: true, key: 'filter' }, + globalFilter: { enabled: true, key: 'filter', mode: 'submit' }, columnFilters: [ { columnId: 'status', searchKey: 'status', type: 'array' }, { columnId: 'vendor_id', searchKey: 'vendor', type: 'array' }, @@ -233,6 +237,11 @@ export function ModelsTable() { applyHeaderSize toolbarProps={{ searchPlaceholder: t('Filter by model name...'), + onSearch: applyGlobalFilter, + searchValue: globalFilterInput, + onSearchValueChange: onGlobalFilterInputChange, + onReset: resetGlobalFilter, + searchLoading: isFetching, filters: [ { columnId: 'status', diff --git a/web/default/src/features/redemption-codes/components/redemptions-table.tsx b/web/default/src/features/redemption-codes/components/redemptions-table.tsx index b889d643..92dfc882 100644 --- a/web/default/src/features/redemption-codes/components/redemptions-table.tsx +++ b/web/default/src/features/redemption-codes/components/redemptions-table.tsx @@ -72,6 +72,10 @@ export function RedemptionsTable() { const { globalFilter, onGlobalFilterChange, + globalFilterInput, + onGlobalFilterInputChange, + applyGlobalFilter, + resetGlobalFilter, columnFilters, onColumnFiltersChange, pagination, @@ -81,7 +85,7 @@ export function RedemptionsTable() { search: route.useSearch(), navigate: route.useNavigate(), pagination: { defaultPage: 1, defaultPageSize: isMobile ? 10 : 20 }, - globalFilter: { enabled: true, key: 'filter' }, + globalFilter: { enabled: true, key: 'filter', mode: 'submit' }, columnFilters: [{ columnId: 'status', searchKey: 'status', type: 'array' }], }) const statusFilter = @@ -199,6 +203,11 @@ export function RedemptionsTable() { skeletonKeyPrefix='redemptions-skeleton' toolbarProps={{ searchPlaceholder: t('Filter by name or ID...'), + onSearch: applyGlobalFilter, + searchValue: globalFilterInput, + onSearchValueChange: onGlobalFilterInputChange, + onReset: resetGlobalFilter, + searchLoading: isFetching, filters: [ { columnId: 'status', diff --git a/web/default/src/features/users/components/users-table.tsx b/web/default/src/features/users/components/users-table.tsx index 0a9a5459..0884b4a1 100644 --- a/web/default/src/features/users/components/users-table.tsx +++ b/web/default/src/features/users/components/users-table.tsx @@ -72,6 +72,10 @@ export function UsersTable() { const { globalFilter, onGlobalFilterChange, + globalFilterInput, + onGlobalFilterInputChange, + applyGlobalFilter, + resetGlobalFilter, columnFilters, onColumnFiltersChange, pagination, @@ -81,7 +85,7 @@ export function UsersTable() { search: route.useSearch(), navigate: route.useNavigate(), pagination: { defaultPage: 1, defaultPageSize: isMobile ? 10 : 20 }, - globalFilter: { enabled: true, key: 'filter' }, + globalFilter: { enabled: true, key: 'filter', mode: 'submit' }, columnFilters: [ { columnId: 'status', searchKey: 'status', type: 'array' }, { @@ -226,6 +230,11 @@ export function UsersTable() { skeletonKeyPrefix='users-skeleton' toolbarProps={{ searchPlaceholder: t('Filter by user ID, username, name or email...'), + onSearch: applyGlobalFilter, + searchValue: globalFilterInput, + onSearchValueChange: onGlobalFilterInputChange, + onReset: resetGlobalFilter, + searchLoading: isFetching, filters: [ { columnId: 'status', diff --git a/web/default/src/features/wallet/components/dialogs/billing-history-dialog.tsx b/web/default/src/features/wallet/components/dialogs/billing-history-dialog.tsx index a5cafa31..07da671b 100644 --- a/web/default/src/features/wallet/components/dialogs/billing-history-dialog.tsx +++ b/web/default/src/features/wallet/components/dialogs/billing-history-dialog.tsx @@ -76,11 +76,13 @@ export function BillingHistoryDialog({ page, pageSize, keyword, + keywordInput, loading, completing, isAdmin, handlePageChange, handlePageSizeChange, + handleSearchInput, handleSearch, handleCompleteOrder, } = useBillingHistory() @@ -117,11 +119,27 @@ export function BillingHistoryDialog({ handleSearch(e.target.value)} + aria-label={t('Search by order number...')} + value={keywordInput} + onChange={(e) => handleSearchInput(e.target.value)} + onKeyDown={(e) => { + if (e.key === 'Enter' && !e.nativeEvent.isComposing) { + e.preventDefault() + handleSearch() + } + }} className='h-9 pl-10' />
+