docs/zh/getting-started/quick-start.md

快速入门指南

概述

本指南将帮助您快速开始使用 AxonHub。只需几分钟，您就可以运行 AxonHub 并发出第一个 API 调用。

先决条件

• Docker 和 Docker Compose（推荐）
• 或者 Go 1.24+ 和 Node.js 18+ 用于开发环境设置
• 来自 AI 提供商的有效 API 密钥（OpenAI、Anthropic 等）

快速设置方法

方法 1：Docker Compose（推荐）

1. 克隆仓库

   git clone https://github.com/looplj/axonhub.git
   cd axonhub
   

2. 配置环境变量

   cp config.example.yml config.yml
   # 使用您喜欢的编辑器编辑 config.yml
   

3. 启动服务

   docker-compose up -d
   

4. 访问应用程序

   • Web 界面：http://localhost:8090
   • 默认凭据：admin@example.com / admin123

方法 2：二进制下载

1. 下载最新版本

   • 访问 GitHub Releases
   • 下载适合您操作系统的二进制文件

2. 解压并运行

   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 格式

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 格式

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. 高级渠道配置

模型映射

模型映射允许您将特定模型的请求重定向到不同的上游模型。这对于以下情况很有用：

• 成本优化：将昂贵的模型映射到更便宜的替代品
• 遗留支持：将已弃用的模型名称映射到当前模型
• 提供商切换：将模型映射到不同的提供商
• 故障转移：配置具有不同提供商的多个渠道

模型映射配置示例：

# 在渠道设置中
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"

使用示例：

# 客户端请求 "gpt-4o-mini" 但获得 "gpt-4o"
response = client.chat.completions.create(
    model="gpt-4o-mini",  # 将被映射到 "gpt-4o"
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

覆盖参数

覆盖参数允许您强制执行渠道特定的默认值，而不受传入请求负载的影响。这对于以下情况很有用：

• 安全性：强制执行安全的参数值
• 一致性：确保跨应用程序的一致行为
• 合规性：满足组织要求
• 优化：为特定用例设置最佳参数

覆盖参数配置示例：

# 在渠道设置中
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:"]
    }

高级覆盖示例：

# 为生产环境强制执行确定性响应
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"]
  }

组合示例：模型映射 + 覆盖参数

# 完整的渠道配置
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. 安全注意事项

   • 避免在开发渠道中覆盖敏感参数
   • 为不同的安全要求使用单独的渠道
   • 定期审查和更新覆盖配置

配置示例

基本配置

# config.yml
server:
  port: 8090
  name: "AxonHub"

db:
  dialect: "sqlite3"
  dsn: "file:axonhub.db?cache=shared&_fk=1"

log:
  level: "info"
  encoding: "json"

生产配置

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 集成
• OpenAI API
• Anthropic API
• Gemini API
• 部署指南

故障排除

常见问题

无法连接到 AxonHub

• 检查服务是否正在运行：docker-compose ps
• 验证端口 8090 是否可用
• 检查防火墙设置

API 密钥身份验证失败

• 验证 API 密钥是否正确配置
• 检查渠道是否已启用
• 确保提供商 API 密钥有效

请求超时

• 在配置中增加 server.llm_request_timeout
• 检查与 AI 提供商的网络连通性

获取帮助

• 查看 GitHub Issues
• 查看 架构文档
• 加入社区讨论

下一步是什么？

现在您已经运行了 AxonHub，探索这些高级功能：

• 设置多个渠道以实现故障转移
• 配置模型映射以优化成本
• 实施请求追踪以进行调试
• 设置使用配额和速率限制
• 与现有的 CI/CD 流水线集成