| # 快速入门指南 | |
| ## 概述 | |
| 本指南将帮助您快速开始使用 AxonHub。只需几分钟，您就可以运行 AxonHub 并发出第一个 API 调用。 | |
| ## 先决条件 | |
| - Docker 和 Docker Compose（推荐） | |
| - 或者 Go 1.24+ 和 Node.js 18+ 用于开发环境设置 | |
| - 来自 AI 提供商的有效 API 密钥（OpenAI、Anthropic 等） | |
| ## 快速设置方法 | |
| ### 方法 1：Docker Compose（推荐） | |
| 1. **克隆仓库** | |
| ```bash | |
| git clone https://github.com/looplj/axonhub.git | |
| cd axonhub | |
| ``` | |
| 2. **配置环境变量** | |
| ```bash | |
| cp config.example.yml config.yml | |
| # 使用您喜欢的编辑器编辑 config.yml | |
| ``` | |
| 3. **启动服务** | |
| ```bash | |
| docker-compose up -d | |
| ``` | |
| 4. **访问应用程序** | |
| - Web 界面：http://localhost:8090 | |
| - 默认凭据：admin@example.com / admin123 | |
| ### 方法 2：二进制下载 | |
| 1. **下载最新版本** | |
| - 访问 [GitHub Releases](https://github.com/looplj/axonhub/releases) | |
| - 下载适合您操作系统的二进制文件 | |
| 2. **解压并运行** | |
| ```bash | |
| unzip axonhub_*.zip | |
| cd axonhub_* | |
| chmod +x axonhub | |
| ./axonhub | |
| ``` | |
| 3. **访问应用程序** | |
| - Web 界面：http://localhost:8090 | |
| ## 第一步 | |
| ### 1. 配置您的第一个渠道 | |
| 1. 登录到 Web 界面 | |
| 2. 导航到 **Channels（渠道）** | |
| 3. 点击 **Add Channel（添加渠道）** | |
| 4. 选择您的提供商（例如，OpenAI） | |
| 5. 输入您的 API 密钥和配置 | |
| 6. 测试连接 | |
| 7. 启用渠道 | |
| ### 2. 创建 API 密钥 | |
| 1. 导航到 **API Keys（API 密钥）** | |
| 2. 点击 **Create API Key（创建 API 密钥）** | |
| 3. 给出一个描述性名称 | |
| 4. 选择适当的范围 | |
| 5. 复制生成的 API 密钥 | |
| ### 3. 发出您的第一个 API 调用 | |
| AxonHub 支持 OpenAI 聊天补全和 Anthropic 消息 API，允许您使用首选的 API 格式访问任何支持的模型。 | |
| #### 使用 OpenAI API 格式 | |
| ```python | |
| from openai import OpenAI | |
| client = OpenAI( | |
| api_key="your-axonhub-api-key", | |
| base_url="http://localhost:8090/v1" | |
| ) | |
| # 调用 OpenAI 模型 | |
| response = client.chat.completions.create( | |
| model="gpt-4o", | |
| messages=[ | |
| {"role": "user", "content": "Hello, AxonHub!"} | |
| ] | |
| ) | |
| print(response.choices[0].message.content) | |
| # 使用 OpenAI API 调用 Anthropic 模型 | |
| response = client.chat.completions.create( | |
| model="claude-3-5-sonnet", | |
| messages=[ | |
| {"role": "user", "content": "Hello, Claude!"} | |
| ] | |
| ) | |
| print(response.choices[0].message.content) | |
| ``` | |
| #### 使用 Anthropic API 格式 | |
| ```python | |
| import requests | |
| # 调用 Anthropic 模型 | |
| response = requests.post( | |
| "http://localhost:8090/anthropic/v1/messages", | |
| headers={ | |
| "Content-Type": "application/json", | |
| "X-API-Key": "your-axonhub-api-key" | |
| }, | |
| json={ | |
| "model": "claude-3-5-sonnet", | |
| "max_tokens": 512, | |
| "messages": [ | |
| { | |
| "role": "user", | |
| "content": [{"type": "text", "text": "Hello, Claude!"}] | |
| } | |
| ] | |
| } | |
| ) | |
| print(response.json()["content"][0]["text"]) | |
| # 使用 Anthropic API 调用 OpenAI 模型 | |
| response = requests.post( | |
| "http://localhost:8090/anthropic/v1/messages", | |
| headers={ | |
| "Content-Type": "application/json", | |
| "X-API-Key": "your-axonhub-api-key" | |
| }, | |
| json={ | |
| "model": "gpt-4o", | |
| "max_tokens": 512, | |
| "messages": [ | |
| { | |
| "role": "user", | |
| "content": [{"type": "text", "text": "Hello, GPT!"}] | |
| } | |
| ] | |
| } | |
| ) | |
| print(response.json()["content"][0]["text"]) | |
| ``` | |
| #### 统一 API 的主要优势 | |
| - **API 互操作性**：使用 OpenAI API 调用 Anthropic 模型，或使用 Anthropic API 调用 OpenAI 模型 | |
| - **零代码更改**：继续使用您现有的 OpenAI 或 Anthropic 客户端 SDK | |
| - **自动翻译**：AxonHub 自动处理 API 格式转换 | |
| - **提供商灵活性**：使用您首选的 API 格式访问任何支持的 AI 提供商 | |
| ### 4. 高级渠道配置 | |
| #### 模型映射 | |
| 模型映射允许您将特定模型的请求重定向到不同的上游模型。这对于以下情况很有用： | |
| - **成本优化**：将昂贵的模型映射到更便宜的替代品 | |
| - **遗留支持**：将已弃用的模型名称映射到当前模型 | |
| - **提供商切换**：将模型映射到不同的提供商 | |
| - **故障转移**：配置具有不同提供商的多个渠道 | |
| **模型映射配置示例：** | |
| ```yaml | |
| # 在渠道设置中 | |
| settings: | |
| modelMappings: | |
| # 将产品特定的别名映射到上游模型 | |
| - from: "gpt-4o-mini" | |
| to: "gpt-4o" | |
| # 将遗留模型名称映射到当前模型 | |
| - from: "claude-3-sonnet" | |
| to: "claude-3.5-sonnet" | |
| # 映射到不同的提供商 | |
| - from: "my-company-model" | |
| to: "gpt-4o" | |
| # 成本优化 | |
| - from: "expensive-model" | |
| to: "cost-effective-model" | |
| ``` | |
| **使用示例：** | |
| ```python | |
| # 客户端请求 "gpt-4o-mini" 但获得 "gpt-4o" | |
| response = client.chat.completions.create( | |
| model="gpt-4o-mini", # 将被映射到 "gpt-4o" | |
| messages=[ | |
| {"role": "user", "content": "Hello!"} | |
| ] | |
| ) | |
| ``` | |
| #### 覆盖参数 | |
| 覆盖参数允许您强制执行渠道特定的默认值，而不受传入请求负载的影响。这对于以下情况很有用： | |
| - **安全性**：强制执行安全的参数值 | |
| - **一致性**：确保跨应用程序的一致行为 | |
| - **合规性**：满足组织要求 | |
| - **优化**：为特定用例设置最佳参数 | |
| **覆盖参数配置示例：** | |
| ```yaml | |
| # 在渠道设置中 | |
| settings: | |
| overrideParameters: | | |
| { | |
| # 基本参数 | |
| "temperature": 0.3, | |
| "max_tokens": 1024, | |
| "top_p": 0.9, | |
| # 强制 JSON 响应 | |
| "response_format": { | |
| "type": "json_object" | |
| }, | |
| # 安全参数 | |
| "presence_penalty": 0.1, | |
| "frequency_penalty": 0.1, | |
| # 提供商特定参数 | |
| "stop_sequences": ["\nHuman:", "\nAssistant:"] | |
| } | |
| ``` | |
| **高级覆盖示例：** | |
| ```yaml | |
| # 为生产环境强制执行确定性响应 | |
| overrideParameters: | | |
| { | |
| "temperature": 0.1, | |
| "max_tokens": 500, | |
| "top_p": 0.95 | |
| } | |
| # 创意写作渠道 | |
| overrideParameters: | | |
| { | |
| "temperature": 0.8, | |
| "max_tokens": 2000, | |
| "frequency_penalty": 0.5 | |
| } | |
| # 代码生成渠道 | |
| overrideParameters: | | |
| { | |
| "temperature": 0.2, | |
| "max_tokens": 4096, | |
| "stop": ["```", "\n\n"] | |
| } | |
| ``` | |
| #### 组合示例：模型映射 + 覆盖参数 | |
| ```yaml | |
| # 完整的渠道配置 | |
| name: "openai-production" | |
| type: "openai" | |
| base_url: "https://api.openai.com/v1" | |
| credentials: | |
| api_key: "your-openai-key" | |
| supported_models: ["gpt-4o", "gpt-4", "gpt-3.5-turbo"] | |
| settings: | |
| modelMappings: | |
| - from: "chat-model" | |
| to: "gpt-4o" | |
| - from: "fast-model" | |
| to: "gpt-3.5-turbo" | |
| overrideParameters: | | |
| { | |
| "temperature": 0.3, | |
| "max_tokens": 1024, | |
| "response_format": { | |
| "type": "json_object" | |
| } | |
| } | |
| ``` | |
| #### 最佳实践 | |
| 1. **模型映射** | |
| - 仅映射到 `supported_models` 中声明的模型 | |
| - 使用描述性的映射名称以提高清晰度 | |
| - 在生产使用前彻底测试映射 | |
| - 为团队成员记录您的映射策略 | |
| 2. **覆盖参数** | |
| - 从保守值开始，根据用例进行调整 | |
| - 考虑对成本和性能的影响 | |
| - 使用不同类型的请求测试覆盖 | |
| - 监控使用模式以优化参数 | |
| 3. **安全注意事项** | |
| - 避免在开发渠道中覆盖敏感参数 | |
| - 为不同的安全要求使用单独的渠道 | |
| - 定期审查和更新覆盖配置 | |
| ## 配置示例 | |
| ### 基本配置 | |
| ```yaml | |
| # config.yml | |
| server: | |
| port: 8090 | |
| name: "AxonHub" | |
| db: | |
| dialect: "sqlite3" | |
| dsn: "file:axonhub.db?cache=shared&_fk=1" | |
| log: | |
| level: "info" | |
| encoding: "json" | |
| ``` | |
| ### 生产配置 | |
| ```yaml | |
| server: | |
| port: 8090 | |
| name: "AxonHub Production" | |
| debug: false | |
| db: | |
| dialect: "postgres" | |
| dsn: "postgres://user:pass@localhost/axonhub?sslmode=disable" | |
| log: | |
| level: "warn" | |
| encoding: "json" | |
| output: "file" | |
| file: | |
| path: "/var/log/axonhub/axonhub.log" | |
| ``` | |
| ## 下一步 | |
| ### 探索功能 | |
| - **追踪**：设置请求追踪以实现可观测性 | |
| - **权限**：配置基于角色的访问控制 | |
| - **模型配置文件**：创建模型映射规则 | |
| - **使用分析**：监控 API 使用和成本 | |
| ### 集成指南 | |
| - [Claude Code 集成](../guides/claude-code-integration.md) | |
| - [OpenAI API](../api-reference/openai-api.md) | |
| - [Anthropic API](../api-reference/anthropic-api.md) | |
| - [Gemini API](../api-reference/gemini-api.md) | |
| - [部署指南](../deployment/configuration.md) | |
| ## 故障排除 | |
| ### 常见问题 | |
| **无法连接到 AxonHub** | |
| - 检查服务是否正在运行：`docker-compose ps` | |
| - 验证端口 8090 是否可用 | |
| - 检查防火墙设置 | |
| **API 密钥身份验证失败** | |
| - 验证 API 密钥是否正确配置 | |
| - 检查渠道是否已启用 | |
| - 确保提供商 API 密钥有效 | |
| **请求超时** | |
| - 在配置中增加 `server.llm_request_timeout` | |
| - 检查与 AI 提供商的网络连通性 | |
| ### 获取帮助 | |
| - 查看 [GitHub Issues](https://github.com/looplj/axonhub/issues) | |
| - 查看 [架构文档](../architecture/erd.md) | |
| - 加入社区讨论 | |
| ## 下一步是什么？ | |
| 现在您已经运行了 AxonHub，探索这些高级功能： | |
| - 设置多个渠道以实现故障转移 | |
| - 配置模型映射以优化成本 | |
| - 实施请求追踪以进行调试 | |
| - 设置使用配额和速率限制 | |
| - 与现有的 CI/CD 流水线集成 | |