knowledge_search/api/CURL_EXAMPLES.md

使用curl访问API服务

1. 启动服务

首先确保已安装依赖并设置环境变量：

# 安装依赖
pip install -r requirements.txt

# 设置OpenRouter API密钥（必需）
export OPENROUTER_API_KEY='your-api-key'

# 可选：设置端口（默认8000）
export API_PORT='8000'

启动服务：

python api/main.py

服务启动后，你会看到类似输出：

INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Pipeline包装器初始化成功
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

2. 测试健康检查端点

curl http://localhost:8000/health

预期响应：

{
  "status": "healthy",
  "pipeline_initialized": true
}

3. 发送搜索请求

基本请求

curl -X POST "http://localhost:8000/what/search" \
  -H "Content-Type: application/json" \
  -d '{
    "original_target": "墨镜",
    "persona_features": [
      {"persona_feature_name": "时尚达人"},
      {"persona_feature_name": "潮流穿搭"},
      {"persona_feature_name": "配饰搭配"}
    ],
    "candidate_words": ["太阳镜", "墨镜", "遮阳", "时尚", "潮流"]
  }'

格式化输出（使用jq）

如果安装了jq，可以格式化JSON输出：

curl -X POST "http://localhost:8000/what/search" \
  -H "Content-Type: application/json" \
  -d '{
    "original_target": "墨镜",
    "persona_features": [
      {"persona_feature_name": "时尚达人"},
      {"persona_feature_name": "潮流穿搭"},
      {"persona_feature_name": "配饰搭配"}
    ],
    "candidate_words": ["太阳镜", "墨镜", "遮阳", "时尚", "潮流"]
  }' | jq '.'

保存响应到文件

curl -X POST "http://localhost:8000/what/search" \
  -H "Content-Type: application/json" \
  -d '{
    "original_target": "墨镜",
    "persona_features": [
      {"persona_feature_name": "时尚达人"},
      {"persona_feature_name": "潮流穿搭"},
      {"persona_feature_name": "配饰搭配"}
    ],
    "candidate_words": ["太阳镜", "墨镜", "遮阳", "时尚", "潮流"]
  }' -o response.json

显示详细请求信息

curl -v -X POST "http://localhost:8000/search" \
  -H "Content-Type: application/json" \
  -d '{
    "original_target": "墨镜",
    "persona_features": [
      {"persona_feature_name": "时尚达人"},
      {"persona_feature_name": "潮流穿搭"},
      {"persona_feature_name": "配饰搭配"}
    ],
    "candidate_words": ["太阳镜", "墨镜", "遮阳", "时尚", "潮流"]
  }'

从文件读取请求体

创建请求文件 request.json：

{
  "original_target": "墨镜",
  "persona_features": [
    {"persona_feature_name": "时尚达人"},
    {"persona_feature_name": "潮流穿搭"},
    {"persona_feature_name": "配饰搭配"}
  ],
  "candidate_words": ["太阳镜", "墨镜", "遮阳", "时尚", "潮流"]
}

然后使用：

curl -X POST "http://localhost:8000/what/search" \
  -H "Content-Type: application/json" \
  -d @request.json

4. 完整示例脚本

创建一个测试脚本 test_api.sh：

#!/bin/bash

# 设置变量
API_URL="http://localhost:8000"
ORIGINAL_TARGET="墨镜"

# 测试健康检查
echo "=== 测试健康检查 ==="
curl -s "${API_URL}/health" | jq '.'
echo -e "\n"

# 测试搜索请求
echo "=== 测试搜索请求 ==="
curl -X POST "${API_URL}/search" \
  -H "Content-Type: application/json" \
  -d "{
    \"original_target\": \"${ORIGINAL_TARGET}\",
    \"persona_features\": [
      {\"persona_feature_name\": \"时尚达人\"},
      {\"persona_feature_name\": \"潮流穿搭\"},
      {\"persona_feature_name\": \"配饰搭配\"}
    ],
    \"candidate_words\": [\"太阳镜\", \"墨镜\", \"遮阳\", \"时尚\", \"潮流\"]
  }" | jq '.'

运行脚本：

chmod +x test_api.sh
./test_api.sh

5. 常见问题

连接被拒绝

如果遇到 Connection refused 错误：

1. 检查服务是否已启动：

   ps aux | grep "api/main.py"
   

   1. 检查端口是否被占用： bash lsof -i :8000

2. 检查防火墙设置

500错误

如果返回500错误，检查：

1. OpenRouter API密钥是否设置： bash echo $OPENROUTER_API_KEY 2. 查看服务日志中的错误信息 ### 400错误 如果返回400错误，检查： 1. JSON格式是否正确 2. 必需字段是否都已提供 3. 字段值是否符合要求（不能为空等） ## 6. 查看API文档 启动服务后，可以在浏览器中访问： - Swagger UI: http://localhost:8000/docs - ReDoc: http://localhost:8000/redoc 这些页面提供了交互式的API文档，可以直接在浏览器中测试API。