zhanggangyong/agent_management
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6eaffba1aa799e37e08d284caa9a86c7d702bd72
agent_management/agent_templates/docs/SEARCH_AGENT_USAGE.md
T
zhanggangyong 6eaffba1aa new version
2026-01-15 17:30:48 +00:00

8.4 KiB
Raw Blame History

Search Agent 使用指南

简介

智能搜索 AI Agent 是一个基于大语言模型的搜索代理，能够理解用户查询意图、自动规划搜索策略、从多个来源获取信息，并生成高质量、有来源引用的答案。

架构

  • 基础镜像: agnettaiji.azurecr.io/ai-agents/search-agent:v1.0
  • 支持平台: linux/amd64, linux/arm64
  • 端口: 8080
  • 协议: HTTP/REST API

功能特点

  • 🧠 智能查询理解: 分析用户意图，提取关键实体
  • 📋 搜索规划: 智能分解问题，制定搜索策略
  • 🔎 多源搜索: 支持 Web 搜索和新闻搜索
  • 📄 内容提取: 智能提取网页核心内容
  • 🎯 结果排序: 基于相关性重排搜索结果
  • ✍️ 答案生成: 综合信息生成结构化回答
  • 🔄 自我反思: 评估答案质量，决定是否迭代

环境变量配置

必需配置

变量名 说明 示例
LLM_BASE_URL LLM API 基础URL https://apis.openroutex.com/openai/deployments/xchat52
LLM_API_KEY LLM API 密钥 sk-xxx
SERPER_API_KEY Serper API 密钥（Google搜索） xxx
JINA_API_KEY Jina API 密钥（内容提取和重排序） jina_xxx

可选配置

变量名 说明 默认值
LLM_MODEL LLM 模型名称 xchat52
MAX_ITERATIONS 最大迭代次数 3
MAX_RESULTS_PER_QUERY 每次搜索最大结果数 10
CONTENT_MAX_LENGTH 内容最大长度 5000
LOG_LEVEL 日志级别 INFO
TIMEOUT 超时时间（秒） 30

部署方式

方式 1: 通过 agent-manager Web API

curl -X POST http://localhost:8000/api/v2/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-search-agent",
    "template_type": "search_agent",
    "image": "agnettaiji.azurecr.io/ai-agents/search-agent:v1.0",
    "replicas": 1,
    "env_vars": {
      "LLM_BASE_URL": "https://apis.openroutex.com/openai/deployments/xchat52",
      "LLM_API_KEY": "your-llm-key",
      "LLM_MODEL": "xchat52",
      "SERPER_API_KEY": "your-serper-key",
      "JINA_API_KEY": "your-jina-key",
      "MAX_ITERATIONS": "3",
      "LOG_LEVEL": "INFO"
    },
    "resources": {
      "cpu_request": "500m",
      "memory_request": "512Mi",
      "cpu_limit": "1000m",
      "memory_limit": "1Gi"
    }
  }'

方式 2: 直接使用 kubectl

# 创建命名空间（如果不存在）
kubectl create namespace agents

# 应用 YAML 配置
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-search-agent
  namespace: agents
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-search-agent
  template:
    metadata:
      labels:
        app: my-search-agent
    spec:
      imagePullSecrets:
      - name: acr-secret
      containers:
      - name: search-agent
        image: agnettaiji.azurecr.io/ai-agents/search-agent:v1.0
        ports:
        - containerPort: 8080
        env:
        - name: LLM_BASE_URL
          value: "https://apis.openroutex.com/openai/deployments/xchat52"
        - name: LLM_API_KEY
          value: "your-llm-key"
        - name: SERPER_API_KEY
          value: "your-serper-key"
        - name: JINA_API_KEY
          value: "your-jina-key"
---
apiVersion: v1
kind: Service
metadata:
  name: my-search-agent
  namespace: agents
spec:
  selector:
    app: my-search-agent
  ports:
  - port: 8080
    targetPort: 8080
EOF

方式 3: 使用 Docker 本地测试

docker run -p 8080:8080 \
  -e LLM_BASE_URL='https://apis.openroutex.com/openai/deployments/xchat52' \
  -e LLM_API_KEY='your-llm-key' \
  -e SERPER_API_KEY='your-serper-key' \
  -e JINA_API_KEY='your-jina-key' \
  agnettaiji.azurecr.io/ai-agents/search-agent:v1.0

API 接口

健康检查

GET /health

# 响应示例
{
  "status": "healthy",
  "pod_name": "search-agent-xxx",
  "template_type": "search_agent",
  "configured": true,
  "timestamp": "2026-01-13T04:45:00.000000"
}

获取状态

GET /status

# 响应示例
{
  "status": "running",
  "pod_name": "search-agent-xxx",
  "template_type": "search_agent",
  "configured": true,
  "timestamp": "2026-01-13T04:45:00.000000"
}

配置 Agent（如果未通过环境变量配置）

POST /configure
Content-Type: application/json

{
  "llm_base_url": "https://apis.openroutex.com/openai/deployments/xchat52",
  "llm_api_key": "your-llm-key",
  "llm_model": "xchat52",
  "serper_api_key": "your-serper-key",
  "jina_api_key": "your-jina-key",
  "max_iterations": 3,
  "max_results_per_query": 10,
  "content_max_length": 5000,
  "log_level": "INFO",
  "timeout": 30
}

执行搜索

POST /search
Content-Type: application/json

{
  "query": "什么是 Kubernetes？",
  "auto_configure": false
}

# 响应示例
{
  "query": "什么是 Kubernetes？",
  "answer": "Kubernetes 是一个开源的容器编排平台...",
  "sources": [
    {
      "index": 1,
      "title": "Kubernetes 官方文档",
      "url": "https://kubernetes.io/docs/"
    }
  ],
  "confidence": "high",
  "iterations": 1,
  "total_sources": 5,
  "search_queries": ["Kubernetes 是什么", "Kubernetes 容器编排"],
  "timestamp": "2026-01-13T04:45:00.000000"
}

聊天接口（别名）

POST /chat
Content-Type: application/json

{
  "query": "Python 和 Go 语言的区别是什么？"
}

使用示例

Python 客户端

import requests

# Agent 服务地址
agent_url = "http://my-search-agent.agents.svc.cluster.local:8080"

# 执行搜索
response = requests.post(
    f"{agent_url}/search",
    json={
        "query": "什么是微服务架构？",
        "auto_configure": False
    }
)

result = response.json()
print(f"答案: {result['answer']}")
print(f"来源数: {len(result['sources'])}")
print(f"置信度: {result['confidence']}")

cURL 示例

# 搜索
curl -X POST http://my-search-agent:8080/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Docker 容器的优势是什么？"
  }'

# 健康检查
curl http://my-search-agent:8080/health

构建和推送

构建镜像

cd /home/taiji/tools/agent-manager/agent_templates
./build_search_agent.sh v1.0

推送到 ACR

在构建过程中选择 y 推送，或手动推送：

# 登录 ACR
az acr login --name agnettaiji

# 构建并推送
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -f search_agent.Dockerfile \
  -t agnettaiji.azurecr.io/ai-agents/search-agent:v1.0 \
  --push \
  .

测试

使用测试脚本

cd /home/taiji/tools/agent-manager/agent_templates
./test_search_agent.sh

手动测试

# 1. 创建 Agent
curl -X POST http://localhost:8000/api/v2/agents \
  -H "Content-Type: application/json" \
  -d @search_agent_config.json

# 2. 查看状态
curl http://localhost:8000/api/v2/agents/my-search-agent

# 3. 测试搜索
curl -X POST http://my-search-agent:8080/search \
  -H "Content-Type: application/json" \
  -d '{"query": "测试查询"}'

# 4. 删除 Agent
curl -X DELETE http://localhost:8000/api/v2/agents/my-search-agent

故障排查

查看日志

kubectl logs -n agents deployment/my-search-agent

查看 Pod 状态

kubectl get pods -n agents -l app=my-search-agent
kubectl describe pod -n agents <pod-name>

常见问题

  1. Agent 无法启动

    • 检查环境变量是否正确配置
    • 确认 ACR secret 已创建
    • 查看 Pod 事件和日志

  2. 搜索失败

    • 确认 API keys 有效
    • 检查网络连接
    • 查看日志中的错误信息

  3. 健康检查失败

    • 确认端口 8080 正常监听
    • 检查容器资源是否充足
    • 查看启动日志

相关文件

  • /home/taiji/tools/agent-manager/agent_templates/search_agent.py - 主程序
  • /home/taiji/tools/agent-manager/agent_templates/search_agent.Dockerfile - Dockerfile
  • /home/taiji/tools/agent-manager/agent_templates/build_search_agent.sh - 构建脚本
  • /home/taiji/tools/agent-manager/agent_templates/test_search_agent.sh - 测试脚本
  • /home/taiji/tools/agent-manager/agent_manager/templates/search_agent.yaml - K8s 模板

技术栈

  • 语言: Python 3.11
  • 框架: FastAPI, Uvicorn
  • LLM: xchat52 (GPT-5.2)
  • 搜索: Serper API (Google 搜索代理)
  • 内容提取: Jina Reader
  • 重排序: Jina Reranker
  • 异步: asyncio

许可

遵循项目主许可证。

Reference in New Issue View Git Blame Copy Permalink