taiji-AI-PAD/Docs/前后端调试说明/APILLAMA_OpenRouter集成说明.md

APILLAMA OpenRouter 集成说明

版本: v1.2.1
最后更新: 2025年12月22日

概述

APILLAMA 处理器已更新为使用 OpenRouter API 调用 Llama 3.1 8B Instruct 模型，无需本地部署模型。这大大简化了部署和维护工作。

模型信息

• 模型: meta-llama/llama-3.1-8b-instruct
• 提供商: OpenRouter
• 模型页面: https://openrouter.ai/meta-llama/llama-3.1-8b-instruct
• 上下文长度: 131,072 tokens
• 定价:
  • 输入: $0.02/M tokens
  • 输出: $0.03/M tokens

配置

环境变量

在 .env 文件中配置以下变量：

# OpenRouter API 配置（用于APILLAMA）
OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

# APILLAMA 模型配置
APILLAMA_MODEL_ID=meta-llama/llama-3.1-8b-instruct
APILLAMA_MAX_TOKENS=2048
APILLAMA_TEMPERATURE=0.3
APILLAMA_TOP_P=0.9

获取 OpenRouter API Key

1. 访问 https://openrouter.ai/
2. 注册/登录账户
3. 在 Dashboard 中创建 API Key
4. 将 API Key 添加到 .env 文件

功能特性

1. LLM 增强处理

当配置了 OpenRouter API Key 时，APILLAMA 处理器会：

• 使用 Llama 3.1 8B Instruct 模型分析 API 文档
• 自动生成结构化的 schema（支持 Pydantic、JSON Schema、OpenAPI 格式）
• 增强 API 描述，使其更清晰和全面
• 提取和规范化参数定义
• 生成示例请求和响应

2. Fallback 机制

如果未配置 OpenRouter API Key 或 API 调用失败，系统会自动回退到基于规则的处理方式，确保服务始终可用。

3. 缓存机制

• 处理结果会缓存到 Redis（24小时）
• 相同输入的重复请求会直接返回缓存结果
• 大大减少 API 调用成本

使用示例

API 调用

curl -X POST "http://localhost:8001/apillama/process" \
  -H "Content-Type: application/json" \
  -d '{
    "api_doc": {
      "title": "Weather API",
      "description": "Get weather information",
      "endpoints": [
        {
          "path": "/weather",
          "method": "GET",
          "parameters": [
            {
              "name": "location",
              "type": "string",
              "required": true
            }
          ]
        }
      ]
    },
    "context": {
      "service": "Weather service",
      "version": "1.0"
    },
    "output_format": "json_schema"
  }'

响应格式

{
  "processed": true,
  "output_format": "json_schema",
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name"
      }
    },
    "required": ["location"]
  },
  "description": "Enhanced API description...",
  "parameters": [
    {
      "name": "location",
      "type": "string",
      "description": "City name",
      "required": true
    }
  ],
  "examples": [
    {
      "name": "basic_example",
      "description": "Basic example request",
      "value": {
        "location": "Beijing"
      }
    }
  ],
  "processing_time": 1.23,
  "confidence_score": 0.95,
  "completeness_score": 0.90
}

支持的输出格式

1. Pydantic: Python Pydantic 模型定义
2. JSON Schema: JSON Schema 格式
3. OpenAPI: OpenAPI 3.0 格式

性能优化

1. 缓存策略

• 所有处理结果都会缓存
• 缓存键基于输入内容的 MD5 哈希
• 缓存时间：24小时

2. 请求优化

• 使用异步 HTTP 客户端
• 超时设置：60秒
• 自动重试机制（在 fallback 中）

3. 成本控制

• 通过缓存减少 API 调用
• 可配置 max_tokens 限制输出长度
• 使用 temperature 和 top_p 控制生成质量

监控和日志

健康检查

curl http://localhost:8001/health

检查 apillama 服务状态：

• healthy: OpenRouter API 正常
• unknown: 未配置 API Key（使用 fallback）
• unhealthy: API 连接失败

Prometheus Metrics

• data_ingestion_apillama_processing_total: 处理总数（按状态）
• data_ingestion_apillama_processing_duration_seconds: 处理耗时
• data_ingestion_cache_hits_total: 缓存命中（类型：apillama）
• data_ingestion_cache_misses_total: 缓存未命中（类型：apillama）

日志

查看服务日志：

docker-compose logs -f data-ingestion | grep APILLAMA

故障排查

问题 1: "OpenRouter API key not provided"

原因: 未配置 OPENROUTER_API_KEY 环境变量

解决:

1. 在 .env 文件中添加 OPENROUTER_API_KEY
2. 重启服务：docker-compose restart data-ingestion

问题 2: API 调用失败

原因:

• API Key 无效
• 网络连接问题
• OpenRouter 服务不可用

解决:

• 系统会自动回退到 fallback 模式
• 检查 API Key 是否有效
• 检查网络连接

问题 3: 处理结果不理想

原因:

• Prompt 可能需要优化
• 模型参数需要调整

解决:

• 调整 APILLAMA_TEMPERATURE（默认 0.3）
• 调整 APILLAMA_TOP_P（默认 0.9）
• 增加 APILLAMA_MAX_TOKENS（默认 2048）

最佳实践

1. 配置 API Key: 确保在 .env 文件中配置有效的 OpenRouter API Key
2. 监控成本: 定期检查 OpenRouter 使用情况，通过缓存减少调用
3. 优化 Prompt: 根据实际需求调整 prompt 模板
4. 使用缓存: 充分利用 Redis 缓存，避免重复处理
5. 错误处理: 系统已实现 fallback 机制，确保服务可用性

相关链接

• OpenRouter 官网
• Llama 3.1 8B Instruct 模型页面
• OpenRouter API 文档
• 项目文档

更新日志

• 2025-12-22: 集成 OpenRouter API，使用 Llama 3.1 8B Instruct 模型
• 之前: 使用本地部署模型（已废弃）