API 访问与密钥管理

AnythingLLM 提供强大的 RESTful API，让开发者能够将 AI 对话功能集成到自己的应用程序中。本指南将详细介绍如何获取 API 访问权限、管理 API 密钥以及使用各种 API 端点。

API 概述

API 特性

RESTful 设计：遵循 REST 架构原则
JSON 格式：使用 JSON 进行数据交换
认证安全：基于 API 密钥的安全认证
速率限制：合理的 API 调用频率限制
版本控制：支持 API 版本管理
详细文档：完整的 API 文档和示例

支持的功能

核心功能：
- 对话管理：创建、管理和删除对话
- 消息发送：发送消息并获取 AI 响应
- 工作空间管理：管理工作空间和设置
- 文档管理：上传、管理和搜索文档

高级功能：
- 用户管理：管理用户账户和权限
- 系统配置：配置系统设置
- 监控统计：获取使用统计和监控数据
- 事件通知：接收系统事件通知

API 密钥管理

创建 API 密钥

访问 API 设置
- 登录 AnythingLLM 管理界面
- 导航到"设置" > "API 密钥"
- 点击"创建新密钥"

配置密钥信息

json

{
  "name": "我的应用 API 密钥",
  "description": "用于集成到我的 Web 应用",
  "permissions": ["chat", "workspace", "documents"],
  "expiration": "2024-12-31",
  "rate_limit": 1000
}

权限设置

基础权限：
- read: 读取数据权限
- write: 写入数据权限
- delete: 删除数据权限

功能权限：
- chat: 对话功能权限
- workspace: 工作空间管理权限
- documents: 文档管理权限
- users: 用户管理权限
- admin: 管理员权限

密钥安全管理

安全最佳实践：
- 定期轮换：定期更换 API 密钥
- 最小权限：只授予必要的权限
- 安全存储：安全存储密钥，避免硬编码
- 监控使用：监控 API 密钥的使用情况

存储建议：
- 环境变量：使用环境变量存储密钥
- 密钥管理服务：使用专业的密钥管理服务
- 加密存储：对存储的密钥进行加密
- 访问控制：限制密钥的访问权限

密钥操作

查看密钥：查看现有的 API 密钥列表
编辑密钥：修改密钥权限和设置
禁用密钥：临时禁用密钥
删除密钥：永久删除不再使用的密钥
重新生成：重新生成密钥值

API 认证

认证方式

AnythingLLM API 使用 Bearer Token 认证：

bash

# 在请求头中包含 API 密钥
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://your-anythingllm-instance.com/api/v1/workspaces

认证示例

javascript

// JavaScript 示例
const apiKey = process.env.ANYTHINGLLM_API_KEY;
const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

fetch('https://your-instance.com/api/v1/workspaces', {
  method: 'GET',
  headers: headers
})
.then(response => response.json())
.then(data => console.log(data));

python

# Python 示例
import requests
import os

api_key = os.getenv('ANYTHINGLLM_API_KEY')
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://your-instance.com/api/v1/workspaces',
    headers=headers
)
data = response.json()

核心 API 端点

工作空间 API

bash

# 获取所有工作空间
GET /api/v1/workspaces

# 创建新工作空间
POST /api/v1/workspaces
{
  "name": "新工作空间",
  "description": "工作空间描述"
}

# 获取特定工作空间
GET /api/v1/workspaces/{workspace_id}

# 更新工作空间
PUT /api/v1/workspaces/{workspace_id}
{
  "name": "更新的名称",
  "settings": {...}
}

# 删除工作空间
DELETE /api/v1/workspaces/{workspace_id}

对话 API

bash

# 发送消息
POST /api/v1/workspaces/{workspace_id}/chat
{
  "message": "你好，请帮我分析这个文档",
  "mode": "chat",
  "include_sources": true
}

# 获取对话历史
GET /api/v1/workspaces/{workspace_id}/chats

# 获取特定对话
GET /api/v1/workspaces/{workspace_id}/chats/{chat_id}

# 删除对话
DELETE /api/v1/workspaces/{workspace_id}/chats/{chat_id}

文档 API

bash

# 上传文档
POST /api/v1/workspaces/{workspace_id}/documents
Content-Type: multipart/form-data
{
  "file": [文件数据],
  "metadata": {
    "title": "文档标题",
    "description": "文档描述"
  }
}

# 获取文档列表
GET /api/v1/workspaces/{workspace_id}/documents

# 搜索文档
GET /api/v1/workspaces/{workspace_id}/documents/search?q=搜索关键词

# 删除文档
DELETE /api/v1/workspaces/{workspace_id}/documents/{document_id}

用户管理 API

bash

# 获取用户列表
GET /api/v1/users

# 创建用户
POST /api/v1/users
{
  "username": "newuser",
  "email": "user@example.com",
  "role": "user"
}

# 更新用户
PUT /api/v1/users/{user_id}
{
  "role": "admin",
  "permissions": ["workspace:read", "workspace:write"]
}

# 删除用户
DELETE /api/v1/users/{user_id}

响应格式

成功响应

json

{
  "success": true,
  "data": {
    "id": "workspace_123",
    "name": "我的工作空间",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "message": "操作成功完成"
}

错误响应

json

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "请求参数无效",
    "details": {
      "field": "name",
      "issue": "名称不能为空"
    }
  }
}

分页响应

json

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

错误处理

HTTP 状态码

成功状态码：
- 200 OK: 请求成功
- 201 Created: 资源创建成功
- 204 No Content: 删除成功

客户端错误：
- 400 Bad Request: 请求参数错误
- 401 Unauthorized: 认证失败
- 403 Forbidden: 权限不足
- 404 Not Found: 资源不存在
- 429 Too Many Requests: 请求频率超限

服务器错误：
- 500 Internal Server Error: 服务器内部错误
- 502 Bad Gateway: 网关错误
- 503 Service Unavailable: 服务不可用

错误代码

认证错误：
- AUTH_INVALID_TOKEN: 无效的 API 密钥
- AUTH_EXPIRED_TOKEN: API 密钥已过期
- AUTH_INSUFFICIENT_PERMISSIONS: 权限不足

请求错误：
- INVALID_REQUEST: 请求格式错误
- MISSING_PARAMETER: 缺少必需参数
- INVALID_PARAMETER: 参数值无效

资源错误：
- RESOURCE_NOT_FOUND: 资源不存在
- RESOURCE_CONFLICT: 资源冲突
- RESOURCE_LIMIT_EXCEEDED: 资源限制超出

系统错误：
- INTERNAL_ERROR: 内部系统错误
- SERVICE_UNAVAILABLE: 服务暂时不可用
- RATE_LIMIT_EXCEEDED: 请求频率超限

速率限制

限制策略

默认限制：
- 每分钟 60 次请求
- 每小时 1000 次请求
- 每天 10000 次请求

高级用户：
- 每分钟 120 次请求
- 每小时 2000 次请求
- 每天 20000 次请求

企业用户：
- 自定义限制
- 专用配额
- 优先级处理

限制响应头

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995200
X-RateLimit-Window: 60

处理速率限制

javascript

async function makeAPIRequest(url, options) {
  try {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitTime = (resetTime * 1000) - Date.now();
      
      console.log(`速率限制，等待 ${waitTime}ms`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
      
      // 重试请求
      return makeAPIRequest(url, options);
    }
    
    return response.json();
  } catch (error) {
    console.error('API 请求失败:', error);
    throw error;
  }
}

SDK 和客户端库

官方 SDK

javascript

// JavaScript/Node.js SDK
npm install @anythingllm/sdk

const AnythingLLM = require('@anythingllm/sdk');
const client = new AnythingLLM({
  apiKey: process.env.ANYTHINGLLM_API_KEY,
  baseURL: 'https://your-instance.com'
});

// 发送消息
const response = await client.chat.send({
  workspaceId: 'workspace_123',
  message: '你好，世界！'
});

python

# Python SDK
pip install anythingllm-python

from anythingllm import AnythingLLM

client = AnythingLLM(
    api_key=os.getenv('ANYTHINGLLM_API_KEY'),
    base_url='https://your-instance.com'
)

# 发送消息
response = client.chat.send(
    workspace_id='workspace_123',
    message='你好，世界！'
)

社区客户端库

Go: anythingllm-go
PHP: anythingllm-php
Ruby: anythingllm-ruby
Java: anythingllm-java

集成示例

Web 应用集成

javascript

// React 组件示例
import React, { useState } from 'react';

function ChatComponent() {
  const [message, setMessage] = useState('');
  const [response, setResponse] = useState('');

  const sendMessage = async () => {
    try {
      const res = await fetch('/api/v1/workspaces/my-workspace/chat', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.REACT_APP_API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ message })
      });
      
      const data = await res.json();
      setResponse(data.data.response);
    } catch (error) {
      console.error('发送消息失败:', error);
    }
  };

  return (
    <div>
      <input 
        value={message}
        onChange={(e) => setMessage(e.target.value)}
        placeholder="输入您的消息..."
      />
      <button onClick={sendMessage}>发送</button>
      <div>{response}</div>
    </div>
  );
}

移动应用集成

swift

// iOS Swift 示例
import Foundation

class AnythingLLMClient {
    private let apiKey: String
    private let baseURL: String
    
    init(apiKey: String, baseURL: String) {
        self.apiKey = apiKey
        self.baseURL = baseURL
    }
    
    func sendMessage(workspaceId: String, message: String, completion: @escaping (Result<String, Error>) -> Void) {
        guard let url = URL(string: "\(baseURL)/api/v1/workspaces/\(workspaceId)/chat") else {
            completion(.failure(NSError(domain: "InvalidURL", code: 0, userInfo: nil)))
            return
        }
        
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        
        let body = ["message": message]
        request.httpBody = try? JSONSerialization.data(withJSONObject: body)
        
        URLSession.shared.dataTask(with: request) { data, response, error in
            // 处理响应
        }.resume()
    }
}

监控和调试

API 日志

启用 API 请求日志记录：

json

{
  "logging": {
    "level": "info",
    "api_requests": true,
    "include_headers": false,
    "include_body": true
  }
}

调试工具

API 测试工具：内置的 API 测试界面
请求日志：详细的请求和响应日志
性能监控：API 响应时间监控
错误追踪：错误日志和堆栈跟踪

监控指标

性能指标：
- 响应时间：平均和 P95 响应时间
- 吞吐量：每秒请求数
- 错误率：错误请求的百分比
- 可用性：服务可用时间百分比

使用指标：
- API 调用次数：总调用次数
- 活跃用户：使用 API 的活跃用户数
- 热门端点：最常用的 API 端点
- 资源使用：CPU、内存、存储使用情况

最佳实践

API 设计

版本控制：使用 API 版本控制
幂等性：确保操作的幂等性
缓存策略：合理使用缓存
错误处理：统一的错误处理机制

安全实践

HTTPS 使用：始终使用 HTTPS
输入验证：验证所有输入参数
输出编码：对输出进行适当编码
审计日志：记录重要操作的审计日志

性能优化

批量操作：使用批量 API 减少请求次数
分页查询：对大量数据使用分页
异步处理：对耗时操作使用异步处理
连接池：使用连接池管理 HTTP 连接

API 是 AnythingLLM 强大功能的重要接口，合理使用可以构建出色的 AI 应用程序。

API 访问与密钥管理 ​

API 概述 ​

API 特性 ​

支持的功能 ​

API 密钥管理 ​

创建 API 密钥 ​

密钥安全管理 ​

密钥操作 ​

API 认证 ​

认证方式 ​

认证示例 ​

核心 API 端点 ​

工作空间 API ​

对话 API ​

文档 API ​

用户管理 API ​

响应格式 ​

成功响应 ​

错误响应 ​

分页响应 ​

错误处理 ​

HTTP 状态码 ​

错误代码 ​

速率限制 ​

限制策略 ​

限制响应头 ​

处理速率限制 ​

SDK 和客户端库 ​

官方 SDK ​

社区客户端库 ​

集成示例 ​

Web 应用集成 ​

移动应用集成 ​

监控和调试 ​

API 日志 ​

调试工具 ​

监控指标 ​

最佳实践 ​

API 设计 ​

安全实践 ​

性能优化 ​

API 访问与密钥管理

API 概述

API 特性

支持的功能

API 密钥管理

创建 API 密钥

密钥安全管理

密钥操作

API 认证

认证方式

认证示例

核心 API 端点

工作空间 API

对话 API

文档 API

用户管理 API

响应格式

成功响应

错误响应

分页响应

错误处理

HTTP 状态码

错误代码

速率限制

限制策略

限制响应头

处理速率限制

SDK 和客户端库

官方 SDK

社区客户端库

集成示例

Web 应用集成

移动应用集成

监控和调试

API 日志

调试工具

监控指标

最佳实践

API 设计

安全实践

性能优化