Airweave TypeScript SDK：前端应用接入搜索API的完整教程

荣宣廷

769人浏览 · 2025-08-30 07:27:08

荣宣廷 · 2025-08-30 07:27:08 发布

Airweave TypeScript SDK：前端应用接入搜索API的完整教程

【免费下载链接】airweave Turn any app into agent knowledge 项目地址: https://gitcode.com/GitHub_Trending/ai/airweave

概述

还在为前端应用集成智能搜索功能而烦恼吗？Airweave TypeScript SDK提供了完整的解决方案，让您的前端应用能够轻松接入强大的语义搜索API。本文将带您从零开始，完整掌握Airweave搜索API的集成方法。

通过本文，您将学会：

✅ Airweave SDK的安装和配置
✅ 认证和权限管理的最佳实践
✅ 执行基础搜索和高级过滤查询
✅ 处理搜索结果和分页逻辑
✅ 错误处理和性能优化技巧

环境准备

安装依赖

首先安装Airweave TypeScript SDK：

npm install @airweave/sdk
# 或者使用 yarn
yarn add @airweave/sdk

基础配置

import { AirweaveSDKClient, AirweaveSDKEnvironment } from "@airweave/sdk";

// 初始化SDK客户端
const client = new AirweaveSDKClient({
  apiKey: process.env.AIRWEAVE_API_KEY, // 从环境变量获取API密钥
  environment: process.env.NODE_ENV === 'production' 
    ? AirweaveSDKEnvironment.Production 
    : AirweaveSDKEnvironment.Local
});

认证与权限管理

API密钥管理

// 创建API密钥
const createApiKey = async (name: string, permissions: string[]) => {
  try {
    const response = await client.apiKeys.createApiKey({
      name,
      permissions
    });
    return response.data;
  } catch (error) {
    console.error('创建API密钥失败:', error);
    throw error;
  }
};

// 获取API密钥列表
const listApiKeys = async () => {
  const response = await client.apiKeys.listApiKeys();
  return response.data;
};

组织上下文管理

// 设置当前组织上下文
const setOrganizationContext = (organizationId: string) => {
  client.setOrganizationId(organizationId);
};

// 清除组织上下文
const clearOrganizationContext = () => {
  client.clearOrganizationId();
};

搜索API核心功能

基础搜索查询

// 执行简单搜索
const searchEntities = async (query: string, collectionId?: string) => {
  const response = await client.search.searchEntities({
    query,
    collection_id: collectionId,
    limit: 10,
    offset: 0
  });
  
  return {
    results: response.data.results,
    total: response.data.total_count,
    hasMore: response.data.has_more
  };
};

// 示例使用
const results = await searchEntities("项目进度报告", "proj-collection-123");

高级过滤搜索

// 带过滤条件的搜索
const searchWithFilters = async (params: {
  query: string;
  collectionId?: string;
  filters?: Record<string, any>;
  sortBy?: string;
  sortOrder?: 'asc' | 'desc';
}) => {
  const response = await client.search.searchEntities({
    query: params.query,
    collection_id: params.collectionId,
    filters: params.filters,
    sort_by: params.sortBy,
    sort_order: params.sortOrder,
    limit: 20,
    offset: 0
  });
  
  return response.data;
};

// 使用示例：搜索特定时间范围内的文档
const filteredResults = await searchWithFilters({
  query: "季度报告",
  filters: {
    created_at: {
      gte: "2024-01-01",
      lte: "2024-03-31"
    },
    file_type: "pdf"
  },
  sortBy: "created_at",
  sortOrder: "desc"
});

分页搜索实现

interface PaginatedSearchParams {
  query: string;
  collectionId?: string;
  page: number;
  pageSize: number;
  filters?: Record<string, any>;
}

const paginatedSearch = async (params: PaginatedSearchParams) => {
  const offset = (params.page - 1) * params.pageSize;
  
  const response = await client.search.searchEntities({
    query: params.query,
    collection_id: params.collectionId,
    filters: params.filters,
    limit: params.pageSize,
    offset: offset
  });
  
  return {
    items: response.data.results,
    pagination: {
      currentPage: params.page,
      pageSize: params.pageSize,
      totalItems: response.data.total_count,
      totalPages: Math.ceil(response.data.total_count / params.pageSize),
      hasNext: response.data.has_more,
      hasPrev: params.page > 1
    }
  };
};

集合管理

创建和管理搜索集合

// 创建新的搜索集合
const createCollection = async (name: string, description?: string) => {
  const response = await client.collections.createCollection({
    name,
    description
  });
  return response.data;
};

// 获取集合列表
const listCollections = async () => {
  const response = await client.collections.listCollections();
  return response.data;
};

// 更新集合配置
const updateCollection = async (collectionId: string, updates: {
  name?: string;
  description?: string;
  config?: any;
}) => {
  const response = await client.collections.updateCollection(collectionId, updates);
  return response.data;
};

错误处理与重试机制

健壮的错误处理

class AirweaveSearchService {
  private client: AirweaveSDKClient;
  private maxRetries: number = 3;
  private retryDelay: number = 1000;

  constructor(apiKey: string, environment: AirweaveSDKEnvironment) {
    this.client = new AirweaveSDKClient({ apiKey, environment });
  }

  async searchWithRetry(params: any, retryCount: number = 0): Promise<any> {
    try {
      return await this.client.search.searchEntities(params);
    } catch (error) {
      if (this.shouldRetry(error) && retryCount < this.maxRetries) {
        await this.delay(this.retryDelay * Math.pow(2, retryCount));
        return this.searchWithRetry(params, retryCount + 1);
      }
      throw this.normalizeError(error);
    }
  }

  private shouldRetry(error: any): boolean {
    // 网络错误、速率限制、服务器错误等应该重试
    return error.code === 'NETWORK_ERROR' || 
           error.status === 429 || 
           error.status >= 500;
  }

  private delay(ms: number): Promise<void> {
    return new Promise(resolve => setTimeout(resolve, ms));
  }

  private normalizeError(error: any): Error {
    if (error.response?.data?.error) {
      return new Error(error.response.data.error);
    }
    return error;
  }
}

性能优化实践

请求缓存机制

class SearchCache {
  private cache = new Map<string, { data: any; timestamp: number }>();
  private cacheTTL: number = 5 * 60 * 1000; // 5分钟缓存

  async getCachedSearch(query: string, params: any): Promise<any> {
    const cacheKey = this.generateCacheKey(query, params);
    const cached = this.cache.get(cacheKey);

    if (cached && Date.now() - cached.timestamp < this.cacheTTL) {
      return cached.data;
    }

    const result = await this.performSearch(query, params);
    this.cache.set(cacheKey, { data: result, timestamp: Date.now() });
    return result;
  }

  private generateCacheKey(query: string, params: any): string {
    return JSON.stringify({ query, ...params });
  }

  clearCache(): void {
    this.cache.clear();
  }
}

防抖搜索实现

import { debounce } from 'lodash-es';

class DebouncedSearch {
  private debouncedSearch: Function;

  constructor(client: AirweaveSDKClient, delay: number = 300) {
    this.debouncedSearch = debounce(
      async (query: string, callback: (results: any) => void) => {
        try {
          const results = await client.search.searchEntities({ query, limit: 5 });
          callback(results.data);
        } catch (error) {
          console.error('搜索失败:', error);
          callback([]);
        }
      },
      delay
    );
  }

  search(query: string, callback: (results: any) => void): void {
    this.debouncedSearch(query, callback);
  }

  cancel(): void {
    this.debouncedSearch.cancel();
  }
}

完整示例应用

React搜索组件示例

import React, { useState, useEffect, useCallback } from 'react';
import { AirweaveSDKClient, AirweaveSDKEnvironment } from "@airweave/sdk";

const SearchComponent: React.FC = () => {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState<any[]>([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const client = new AirweaveSDKClient({
    apiKey: process.env.REACT_APP_AIRWEAVE_API_KEY!,
    environment: AirweaveSDKEnvironment.Production
  });

  const performSearch = useCallback(async (searchQuery: string) => {
    if (!searchQuery.trim()) {
      setResults([]);
      return;
    }

    setLoading(true);
    setError(null);

    try {
      const response = await client.search.searchEntities({
        query: searchQuery,
        limit: 10,
        filters: {
          // 可以根据需要添加特定过滤条件
        }
      });
      
      setResults(response.data.results);
    } catch (err) {
      setError('搜索失败，请稍后重试');
      console.error('搜索错误:', err);
    } finally {
      setLoading(false);
    }
  }, [client]);

  useEffect(() => {
    const timeoutId = setTimeout(() => {
      performSearch(query);
    }, 500);

    return () => clearTimeout(timeoutId);
  }, [query, performSearch]);

  return (
    <div className="search-container">
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="搜索文档、消息、任务..."
        className="search-input"
      />
      
      {loading && <div className="loading">搜索中...</div>}
      {error && <div className="error">{error}</div>}
      
      <div className="results">
        {results.map((result, index) => (
          <div key={index} className="result-item">
            <h4>{result.title || result.name}</h4>
            <p>{result.snippet}</p>
            <div className="meta">
              <span>来源: {result.source}</span>
              <span>时间: {new Date(result.created_at).toLocaleDateString()}</span>
            </div>
          </div>
        ))}
      </div>
    </div>
  );
};

export default SearchComponent;

最佳实践总结

安全实践

// 1. API密钥安全存储
const secureApiKeyManagement = {
  // 使用环境变量而非硬编码
  apiKey: process.env.AIRWEAVE_API_KEY,
  
  // 定期轮换密钥
  rotateKey: async (oldKey: string) => {
    // 实现密钥轮换逻辑
  },
  
  // 密钥使用监控
  monitorUsage: (key: string) => {
    // 监控API密钥使用情况
  }
};

性能监控

// 搜索性能监控
const searchPerformance = {
  trackSearchLatency: async (query: string, startTime: number) => {
    const latency = Date.now() - startTime;
    // 发送到监控系统
    console.log(`搜索查询 "${query}" 耗时: ${latency}ms`);
  },
  
  trackSearchSuccessRate: (success: boolean) => {
    // 跟踪搜索成功率
  }
};

故障排除指南

常见问题解决

问题	原因	解决方案
认证失败	API密钥无效或过期	检查密钥有效性，重新生成
速率限制	请求过于频繁	实现请求队列和重试机制
网络错误	连接问题	检查网络连接，实现重试逻辑
数据不一致	缓存问题	清除缓存，重新同步数据

调试技巧

// 启用详细日志
const enableDebugLogging = () => {
  // 在开发环境中启用详细日志
  if (process.env.NODE_ENV === 'development') {
    console.log('Airweave SDK调试模式已启用');
    // 可以添加更多的调试信息
  }
};

// 请求追踪
const trackRequest = (requestId: string, details: any) => {
  console.log(`请求ID: ${requestId}`, details);
};

通过本教程，您已经掌握了Airweave TypeScript SDK的完整使用方法。从基础配置到高级功能，从错误处理到性能优化，这些实践将帮助您构建高效、稳定的搜索功能。

记住关键要点：