跳至主要內容

第2406篇：平台型AI的API设计——如何设计一个开发者愿意使用的AI API

老张2026/4/30大约 8 分钟

第2406篇：平台型AI的API设计——如何设计一个开发者愿意使用的AI API

适读人群：需要设计AI API供其他开发者使用的平台工程师 | 阅读时长：约14分钟 | 核心价值：掌握AI API设计的核心原则和最佳实践，让你的API成为开发者喜爱的工具

我第一次被其他开发者吐槽自己设计的API，是在内部开发者大会上。

一个同事站起来说：「能不能问一下那个AI摘要API是谁设计的？我接了三天，每次调用我都不确定它会返回什么，有时候是JSON，有时候是纯文字，超时还没有具体信息，错误码也不统一……」

然后很多人点头。

那个API是我设计的。

那次之后，我研究了OpenAI、Anthropic、Gemini的API设计，也研究了AWS、Stripe、Twilio这些非AI但被开发者广泛称赞的API。

我发现AI API设计有一套独立的最佳实践，和普通的RESTful API有显著的不同。

为什么AI API设计是个特殊问题

AI API和普通CRUD API的根本差异：

  1. 响应时间不确定：普通API通常50-200ms，AI API可能1-30秒，甚至更长
  2. 输出长度不确定：同样的请求可能返回100字，也可能返回5000字
  3. 输出质量是概率性的：两次相同的请求可能返回不同质量的结果
  4. 有Token限制：输入/输出都有硬性上限
  5. 有成本：API调用有真实的边际成本，滥用会造成成本损失

这些特殊性决定了AI API在以下几个方面需要特别设计：异步流式处理、请求规格验证、错误信息设计、限流策略、成本控制。

AI API设计的十条原则

原则1：支持流式响应（SSE/WebSocket）

这是AI API最重要的一条。任何响应时间可能超过3秒的AI API都应该支持流式输出。

@RestController
@RequestMapping("/v1/ai")
public class AIApiController {
    
    private final ChatClient chatClient;
    
    /**
     * 同步接口（适合响应时间可控的简单任务）
     */
    @PostMapping("/summarize")
    public ResponseEntity<AIResponse> summarize(@RequestBody @Valid SummarizeRequest request) {
        // 对于摘要这种可能很慢的任务，返回一个job ID
        String jobId = UUID.randomUUID().toString();
        jobQueue.submit(jobId, request);
        
        return ResponseEntity.accepted()
            .header("X-Job-Id", jobId)
            .body(new AIResponse(jobId, "processing", null, null));
    }
    
    /**
     * 流式接口（主要交互方式，响应更快更流畅）
     */
    @PostMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<ServerSentEvent<ChatStreamEvent>> chatStream(
            @RequestBody @Valid ChatRequest request,
            @RequestHeader("X-Request-Id") String requestId) {
        
        return Flux.<ServerSentEvent<ChatStreamEvent>>create(sink -> {
            // 发送处理开始事件
            sink.next(ServerSentEvent.<ChatStreamEvent>builder()
                .id(requestId + "-start")
                .event("message_start")
                .data(new ChatStreamEvent("message_start", null, 
                    new MessageStartData(requestId)))
                .build());
            
            // 流式获取内容
            chatClient.prompt()
                .system(request.systemPrompt())
                .user(request.userMessage())
                .stream()
                .chatResponse()
                .subscribe(
                    chunk -> sink.next(ServerSentEvent.<ChatStreamEvent>builder()
                        .id(requestId + "-" + System.currentTimeMillis())
                        .event("content_block_delta")
                        .data(new ChatStreamEvent("content_block_delta",
                            chunk.getResult().getOutput().getContent(), null))
                        .build()),
                    error -> {
                        sink.next(ServerSentEvent.<ChatStreamEvent>builder()
                            .event("error")
                            .data(new ChatStreamEvent("error", null, 
                                new ErrorData(mapErrorCode(error), error.getMessage())))
                            .build());
                        sink.complete();
                    },
                    () -> {
                        // 发送结束事件，包含使用量统计
                        sink.next(ServerSentEvent.<ChatStreamEvent>builder()
                            .event("message_delta")
                            .data(new ChatStreamEvent("message_delta", null,
                                new MessageEndData("end_turn", getTokenUsage(requestId))))
                            .build());
                        sink.complete();
                    }
                );
        });
    }
}

原则2：统一且精确的错误码体系

/**
 * AI API统一错误码定义
 * 参考了OpenAI和Anthropic的错误设计，取长补短
 */
public enum AIApiError {
    
    // 4xx：客户端错误
    INVALID_REQUEST(400, "invalid_request", "请求参数不合法"),
    AUTHENTICATION_FAILED(401, "authentication_failed", "API Key无效或已过期"),
    PERMISSION_DENIED(403, "permission_denied", "无权访问此资源或功能"),
    RATE_LIMIT_EXCEEDED(429, "rate_limit_exceeded", "请求频率超过限制"),
    TOKEN_LIMIT_EXCEEDED(400, "token_limit_exceeded", "输入Token超过模型上限"),
    CONTENT_FILTERED(400, "content_filtered", "输入内容不符合安全规范"),
    QUOTA_EXCEEDED(402, "quota_exceeded", "账户配额已用尽"),
    
    // 5xx：服务端错误
    MODEL_UNAVAILABLE(503, "model_unavailable", "模型服务暂时不可用"),
    PROCESSING_TIMEOUT(504, "processing_timeout", "处理超时，请重试或缩短输入"),
    INTERNAL_ERROR(500, "internal_error", "服务内部错误");
    
    final int httpStatus;
    final String code;
    final String message;
    
    AIApiError(int httpStatus, String code, String message) {
        this.httpStatus = httpStatus;
        this.code = code;
        this.message = message;
    }
}

@ControllerAdvice
public class AIApiExceptionHandler {
    
    @ExceptionHandler(AIApiException.class)
    public ResponseEntity<ErrorResponse> handleAIApiException(
            AIApiException ex, HttpServletRequest request) {
        
        AIApiError error = ex.getError();
        
        ErrorResponse response = new ErrorResponse(
            error.code,
            error.message,
            ex.getDetail(),      // 具体的错误详情，帮助开发者调试
            request.getHeader("X-Request-Id"),
            LocalDateTime.now().toString(),
            buildRetryHint(error)  // 告诉开发者如何处理这个错误
        );
        
        return ResponseEntity.status(error.httpStatus).body(response);
    }
    
    private String buildRetryHint(AIApiError error) {
        return switch (error) {
            case RATE_LIMIT_EXCEEDED -> 
                "请在Retry-After响应头指定的秒数后重试";
            case PROCESSING_TIMEOUT -> 
                "建议：1) 缩短输入内容 2) 使用异步接口 3) 直接重试（成功率约85%）";
            case MODEL_UNAVAILABLE -> 
                "模型暂时不可用，请在30秒后重试。如持续超过5分钟请联系支持";
            case CONTENT_FILTERED -> 
                "请检查并修改不符合规范的内容后重新提交，具体规范见文档";
            default -> null;
        };
    }
}

record ErrorResponse(
    String error,
    String message,
    String detail,
    String requestId,
    String timestamp,
    String retryHint
) {}

开发者最头疼的不是遇到错误，而是遇到错误不知道怎么办。retryHint 字段直接告诉开发者下一步该做什么，这一点让API使用体验大幅提升。

原则3：请求规格的防御性验证

@Service
public class RequestValidator {
    
    /**
     * 在请求进入AI处理之前进行全面的规格验证
     * 给开发者清晰的错误信息，而不是让请求进到AI里才发现问题
     */
    public ValidationResult validate(ChatRequest request) {
        List<ValidationError> errors = new ArrayList<>();
        
        // 1. 消息列表不能为空
        if (request.messages() == null || request.messages().isEmpty()) {
            errors.add(new ValidationError("messages", "messages不能为空"));
        } else {
            // 2. 消息结构验证
            for (int i = 0; i < request.messages().size(); i++) {
                Message msg = request.messages().get(i);
                if (msg.role() == null) {
                    errors.add(new ValidationError(
                        "messages[" + i + "].role", "role不能为空"));
                }
                if (msg.content() == null || msg.content().isBlank()) {
                    errors.add(new ValidationError(
                        "messages[" + i + "].content", "content不能为空"));
                }
            }
            
            // 3. 消息角色顺序检查
            if (!isValidRoleSequence(request.messages())) {
                errors.add(new ValidationError("messages", 
                    "消息角色顺序不合法：必须是user/assistant交替，以user开始"));
            }
        }
        
        // 4. Token估算检查（提前给开发者预警）
        int estimatedTokens = estimateTokens(request);
        int modelMaxTokens = getModelMaxTokens(request.model());
        if (estimatedTokens > modelMaxTokens * 0.9) {
            errors.add(new ValidationError("messages", 
                String.format("预估Token数(%d)接近或超过模型上限(%d)，请精简输入",
                    estimatedTokens, modelMaxTokens)));
        }
        
        // 5. 参数范围检查
        if (request.temperature() != null && 
            (request.temperature() < 0 || request.temperature() > 2)) {
            errors.add(new ValidationError("temperature", 
                "temperature必须在0到2之间，推荐值：0.7"));
        }
        
        if (!errors.isEmpty()) {
            return ValidationResult.failed(errors);
        }
        return ValidationResult.passed(estimatedTokens);
    }
}

原则4：提供幂等性支持

开发者遇到超时时会重试，AI API必须支持幂等重试，避免重复计费和重复处理：

@Service
public class IdempotentAIService {
    
    private final Cache<String, AIResponse> idempotencyCache;
    
    /**
     * 基于X-Idempotency-Key实现幂等处理
     * 相同的key在24小时内返回相同的结果，不会重复调用AI
     */
    public AIResponse processIdempotent(String idempotencyKey, ChatRequest request) {
        // 检查是否有缓存的结果
        AIResponse cached = idempotencyCache.getIfPresent(idempotencyKey);
        if (cached != null) {
            return cached.toIdempotentResponse(); // 标记为重复请求的返回
        }
        
        // 检查是否正在处理中（防止并发的相同请求）
        if (processingKeys.contains(idempotencyKey)) {
            throw new AIApiException(AIApiError.RATE_LIMIT_EXCEEDED, 
                "相同的idempotency-key正在处理中，请等待或检查原请求的状态");
        }
        
        processingKeys.add(idempotencyKey);
        try {
            AIResponse response = callAI(request);
            idempotencyCache.put(idempotencyKey, response);
            return response;
        } finally {
            processingKeys.remove(idempotencyKey);
        }
    }
}

原则5：开发者友好的限流

限流是必须的，但限流的设计方式决定了开发者体验：

@Component
public class DeveloperFriendlyRateLimiter {
    
    /**
     * 限流时返回详细的信息，让开发者知道：
     * 1. 哪个维度被限了（RPM？TPM？并发？）
     * 2. 还要等多久
     * 3. 怎么避免被限
     */
    public RateLimitResult check(String apiKey, ChatRequest request) {
        RateLimitConfig config = getConfig(apiKey);
        RateLimitStatus status = checkAllLimits(apiKey, request, config);
        
        if (!status.allowed()) {
            // 在响应头中返回限流信息（符合RFC 6585标准）
            Map<String, String> headers = new LinkedHashMap<>();
            headers.put("X-RateLimit-Limit-RPM", String.valueOf(config.rpm()));
            headers.put("X-RateLimit-Remaining-RPM", String.valueOf(status.remainingRpm()));
            headers.put("X-RateLimit-Reset-RPM", String.valueOf(status.rpmResetAt()));
            headers.put("X-RateLimit-Limit-TPM", String.valueOf(config.tpm()));
            headers.put("X-RateLimit-Remaining-TPM", String.valueOf(status.remainingTpm()));
            headers.put("Retry-After", String.valueOf(status.retryAfterSeconds()));
            
            return RateLimitResult.limited(
                status.limitedBy(),
                headers,
                buildLimitMessage(status, config)
            );
        }
        
        // 即使允许，也返回当前的限制状态，让开发者能提前规划
        return RateLimitResult.allowed(Map.of(
            "X-RateLimit-Remaining-RPM", String.valueOf(status.remainingRpm()),
            "X-RateLimit-Remaining-TPM", String.valueOf(status.remainingTpm())
        ));
    }
    
    private String buildLimitMessage(RateLimitStatus status, RateLimitConfig config) {
        return switch (status.limitedBy()) {
            case RPM -> String.format(
                "超过每分钟请求限制(%d RPM)。将在%d秒后重置。建议：实现指数退避重试，或升级API计划",
                config.rpm(), status.retryAfterSeconds());
            case TPM -> String.format(
                "超过每分钟Token限制(%d TPM)。建议：减少单次请求的输入长度，或降低并发数",
                config.tpm());
            case CONCURRENT -> String.format(
                "超过并发请求限制(%d个)。请等待当前请求完成后再发送新请求",
                config.maxConcurrent());
        };
    }
}

API文档设计：让开发者一看就会用

好的AI API文档要包含：

每个端点的文档必须有：

  1. 请求示例（curl + 各语言SDK示例）
  2. 响应示例（包括成功和各种错误的例子）
  3. 参数详细说明（包括类型、取值范围、默认值）
  4. 使用场景说明（什么时候用这个接口）
  5. 已知限制（Token上限、速率限制等）

SDK设计原则：

// 好的SDK设计：链式调用，符合Java习惯
AIClient client = AIClient.builder()
    .apiKey(System.getenv("AI_API_KEY"))
    .timeout(Duration.ofSeconds(30))
    .maxRetries(3)  // 内置重试
    .build();

// 直观的使用方式
ChatResponse response = client.chat()
    .model("gpt-4o-mini")
    .system("你是一个专业的代码审查员")
    .user("请审查以下Java代码：" + code)
    .temperature(0.3)
    .maxTokens(1000)
    .execute();

// 流式版本同样直观
client.chat()
    .model("gpt-4o-mini")
    .user(userMessage)
    .stream()
    .onToken(token -> System.out.print(token))
    .onComplete(usage -> System.out.println("\n使用了" + usage.totalTokens() + " tokens"))
    .onError(error -> System.err.println("错误：" + error.getMessage()))
    .execute();

总结

设计一个开发者愿意使用的AI API，需要把自己放在调用者的位置思考：

  1. 流式响应：AI API必须支持，这是体验的基础
  2. 精确的错误码 + 处理建议：让开发者不迷茫
  3. 防御性验证：在进入AI之前就发现问题
  4. 幂等性支持：让重试安全
  5. 开发者友好的限流：告诉开发者限的是什么，怎么解决
  6. 完整的文档和SDK：降低接入门槛

一个好的AI API是产品的一部分，它决定了其他开发者能不能成功地在你的平台上构建东西。这不是「API设计规范」的问题，而是产品成败的关键。

编辑此页
最近更新:
贡献者: xiaozhangge