技能 编程开发 AssemblyAI生产部署检查清单

AssemblyAI生产部署检查清单

v20260423
assemblyai-prod-checklist
本清单是一份全面的指南,用于指导将基于AssemblyAI的转录服务安全可靠地部署到生产环境。它覆盖了从前置API密钥检查、健康监测、WebHook处理配置到分阶段推广等全生命周期关键步骤,确保了语音转文字服务的高可用性和可靠性。
获取技能
208 次下载
概览

AssemblyAI Production Checklist

Overview

Complete checklist for deploying AssemblyAI-powered transcription services to production with health checks, monitoring, and rollback procedures.

Prerequisites

  • Staging environment tested and verified
  • Production API key from https://www.assemblyai.com/app/account
  • Deployment pipeline configured
  • Monitoring stack ready

Instructions

Pre-Deployment Checklist

API Key & Auth

  • [ ] Production API key stored in secrets manager (not env files)
  • [ ] Key is separate from dev/staging keys
  • [ ] Temporary token endpoint configured for browser streaming
  • [ ] API key rotation procedure documented

Code Quality

  • [ ] All transcript.status === 'error' cases handled
  • [ ] Rate limit retry with exponential backoff implemented
  • [ ] No hardcoded API keys or audio URLs
  • [ ] PII redaction enabled for sensitive audio content
  • [ ] Webhook URL uses HTTPS
  • [ ] Audio file upload size validated before submission

Error Handling

  • [ ] 429 (rate limit) triggers retry with backoff
  • [ ] 5xx (server error) triggers retry with backoff
  • [ ] 401 (auth error) triggers alert, no retry
  • [ ] transcript.status === 'error' logged with transcript ID and error message
  • [ ] WebSocket disconnect triggers reconnection for streaming
  • [ ] LeMUR errors handled (invalid transcript ID, context too long)

Performance

  • [ ] Transcript results cached where appropriate
  • [ ] Concurrent transcription jobs limited via queue (p-queue or similar)
  • [ ] Webhook processing is async (don't block the response)
  • [ ] Long audio files processed with webhook_url instead of polling

Health Check Implementation

import { AssemblyAI } from 'assemblyai';

const client = new AssemblyAI({
  apiKey: process.env.ASSEMBLYAI_API_KEY!,
});

export async function healthCheck(): Promise<{
  status: 'healthy' | 'degraded' | 'down';
  assemblyai: { connected: boolean; latencyMs: number };
}> {
  const start = Date.now();
  try {
    // List transcripts as a lightweight connectivity check
    await client.transcripts.list({ limit: 1 });
    return {
      status: 'healthy',
      assemblyai: { connected: true, latencyMs: Date.now() - start },
    };
  } catch (error) {
    return {
      status: 'degraded',
      assemblyai: { connected: false, latencyMs: Date.now() - start },
    };
  }
}

Webhook-Based Processing (Recommended for Production)

// Instead of polling, use webhooks for transcription completion
const transcript = await client.transcripts.submit({
  audio: audioUrl,
  webhook_url: 'https://your-app.com/webhooks/assemblyai',
  webhook_auth_header_name: 'X-Webhook-Secret',
  webhook_auth_header_value: process.env.ASSEMBLYAI_WEBHOOK_SECRET!,
  speaker_labels: true,
  sentiment_analysis: true,
});

console.log('Submitted:', transcript.id, '(webhook will fire on completion)');
// Webhook handler
import express from 'express';

app.post('/webhooks/assemblyai', express.json(), async (req, res) => {
  // Verify auth header
  const secret = req.headers['x-webhook-secret'];
  if (secret !== process.env.ASSEMBLYAI_WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const { transcript_id, status } = req.body;

  if (status === 'completed') {
    // Fetch full transcript
    const transcript = await client.transcripts.get(transcript_id);
    await processCompletedTranscript(transcript);
  } else if (status === 'error') {
    console.error(`Transcript ${transcript_id} failed:`, req.body.error);
    await handleFailedTranscript(transcript_id, req.body.error);
  }

  res.status(200).json({ received: true });
});

Monitoring & Alerting

AlertConditionSeverity
API unreachableHealth check fails 3x consecutiveP1
High error rate>5% of transcriptions failP2
Rate limited429 errors > 5/minP2
Auth failureAny 401 responseP1
Slow transcriptionQueue wait > 5 minP3
Webhook delivery failureWebhook retries exhaustedP2

Gradual Rollout

# 1. Pre-flight: verify AssemblyAI API is healthy
curl -s https://status.assemblyai.com/api/v2/status.json | jq '.status.description'

# 2. Deploy to canary (10% traffic)
# 3. Monitor error rate and latency for 10 minutes
# 4. If healthy, roll to 50%, then 100%
# 5. Keep previous version ready for instant rollback

Output

  • Production-ready deployment with health checks
  • Webhook-based transcription processing
  • Monitoring and alerting configuration
  • Gradual rollout strategy

Error Handling

IssueDetectionResponse
API key invalid in prod401 on first callRotate key immediately
Transcription backlogQueue size growingScale workers, check rate limits
Webhook endpoint downMissed completion eventsPoll for stuck transcripts
Audio upload timeoutLarge file failuresIncrease timeout, validate file size

Resources

Next Steps

For version upgrades, see assemblyai-upgrade-migration.

信息
分类 编程开发
名称 assemblyai-prod-checklist
版本 v20260423
大小 5.86KB
更新时间 2026-04-28
语言