Skip to content

API_SPEC.md

Latest commit

 

History

History
226 lines (179 loc) · 5.36 KB

API_SPEC.md

File metadata and controls

226 lines (179 loc) · 5.36 KB

Rovo Dev OpenAI API 规范

本文档详细描述了Rovo Dev OpenAI API的接口规范，完全兼容OpenAI API格式。

基础信息

  • API版本: v1
  • Base URL: http://localhost:8000
  • 协议: HTTP/HTTPS
  • 数据格式: JSON
  • 认证方式: Bearer Token (可选)

认证

如果启用了认证，需要在请求头中包含API密钥：

Authorization: Bearer your-api-key-here

端点详情

1. 健康检查

检查API服务的健康状态。

端点: GET /health

响应示例:

{
  "status": "healthy",
  "uptime": 3600.5,
  "error_count": 0,
  "last_error_time": null,
  "timestamp": 1751610000.123
}

2. 性能统计

获取API服务的性能统计信息。

端点: GET /stats

响应示例:

{
  "request_count": 150,
  "total_time": 45.67,
  "average_time": 0.304,
  "slow_requests": [
    {
      "path": "/v1/chat/completions",
      "method": "POST",
      "time": 12.34,
      "timestamp": 1751610000.123
    }
  ]
}

3. 模型列表

获取可用的AI模型列表。

端点: GET /v1/models

响应示例:

{
  "object": "list",
  "data": [
    {
      "id": "rovo-dev",
      "object": "model",
      "created": 1751610000,
      "owned_by": "atlassian"
    }
  ]
}

4. 聊天完成

主要的聊天完成端点，支持与Rovo Dev AI助手的对话。

端点: POST /v1/chat/completions

请求参数:

参数 类型 必需 默认值 描述
model string 是 - 模型名称，固定为 "rovo-dev"
messages array 是 - 对话消息数组
stream boolean 否 false 是否启用流式响应
temperature number 否 0.3 温度参数 (0.0-2.0)
max_tokens integer 否 null 最大token数
stop string/array 否 null 停止词
presence_penalty number 否 0.0 存在惩罚 (-2.0 to 2.0)
frequency_penalty number 否 0.0 频率惩罚 (-2.0 to 2.0)
top_p number 否 1.0 Top-p采样 (0.0-1.0)
n integer 否 1 生成响应数量 (1-10)
user string 否 null 用户标识

消息格式:

{
  "role": "user|assistant|system",
  "content": "消息内容",
  "name": "可选的发送者名称"
}

请求示例:

{
  "model": "rovo-dev",
  "messages": [
    {
      "role": "user",
      "content": "请解释什么是RESTful API"
    }
  ],
  "stream": false,
  "temperature": 0.3,
  "max_tokens": 1000
}

非流式响应示例:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1751610000,
  "model": "rovo-dev",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "RESTful API是一种基于REST架构风格的Web API设计方法..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 150,
    "total_tokens": 165
  }
}

流式响应示例:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1751610000,"model":"rovo-dev","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1751610000,"model":"rovo-dev","choices":[{"index":0,"delta":{"content":"RESTful"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1751610000,"model":"rovo-dev","choices":[{"index":0,"delta":{"content":" API"},"finish_reason":null}]}

...

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1751610000,"model":"rovo-dev","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

错误处理

API使用标准HTTP状态码和结构化错误响应。

错误响应格式:

{
  "error": {
    "message": "错误描述",
    "type": "错误类型",
    "code": "错误代码",
    "param": "相关参数"
  }
}

常见错误类型:

状态码 错误类型 描述
400 invalid_request_error 请求格式错误或缺少必需参数
401 authentication_error API密钥无效或缺失
404 not_found_error 请求的资源不存在
408 timeout_error 请求超时
429 rate_limit_error 请求频率超出限制
500 api_error 服务器内部错误
503 service_unavailable_error 服务暂时不可用

限制和配额

  • 请求频率: 默认每分钟100次请求（可配置）
  • 并发会话: 默认最多10个并发会话（可配置）
  • 请求超时: 120秒
  • 最大消息长度: 无硬性限制，但受Rovo Dev处理能力影响

最佳实践

  1. 使用流式响应: 对于长文本生成，建议使用 "stream": true
  2. 合理设置温度: 0.3适合大多数场景，创意任务可适当提高
  3. 错误重试: 实现指数退避的重试机制
  4. 会话管理: 避免创建过多并发会话
  5. 内容过滤: 注意输入内容的合规性

兼容性

本API完全兼容OpenAI Chat Completions API格式，可以直接替换OpenAI API端点使用。

支持的OpenAI客户端库：

  • openai (Python)
  • openai (Node.js)
  • 其他兼容OpenAI格式的客户端库

版本历史

  • v1.0.0: 初始版本，支持基础聊天完成功能
  • 未来版本将添加更多OpenAI兼容功能