# Jina Search Agent 请求调用示例

## 服务信息
- **服务名称**: Jina Search Agent
- **版本**: 1.0.0
- **功能**: 使用 Jina Reader API 获取网站内容
- **默认端口**: 8080

## 概述
Jina Search Agent 使用 Jina Reader API 提取和解析网页内容，返回纯文本格式的内容，适合用于内容分析、摘要生成等场景。

---

## API 端点

### 1. 健康检查
**端点**: `GET /health`

**请求示例** (curl):
```bash
curl http://localhost:8080/health
```

**响应示例**:
```json
{
  "status": "healthy",
  "pod_name": "jina-search-agent",
  "template_type": "jina_search_agent",
  "jina_api_configured": true
}
```

---

### 2. 服务信息
**端点**: `GET /`

**请求示例** (curl):
```bash
curl http://localhost:8080/
```

**响应示例**:
```json
{
  "service": "Jina Search Agent",
  "version": "1.0.0",
  "description": "使用Jina Reader API获取网站内容的AI Agent",
  "pod_name": "jina-search-agent",
  "template_type": "jina_search_agent",
  "required_env": {
    "JINA_API_KEY": {
      "description": "Jina API密钥，从 https://jina.ai/ 获取",
      "required": true,
      "configured": true
    }
  },
  "optional_env": {
    "SERVICE_PORT": {
      "description": "HTTP服务端口",
      "default": "8080"
    }
  }
}
```

---

### 3. 搜索/提取网页内容
**端点**: `POST /search`

使用 Jina Reader API 提取指定 URL 的网页内容。

**请求体**:
```json
{
  "url": "https://example.com",
  "jina_api_key": "your-jina-api-key",
  "user_id": "user123",
  "timeout": 30
}
```

**请求示例** (curl):
```bash
curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://python.org",
    "jina_api_key": "jina_xxx",
    "user_id": "user123"
  }'
```

**请求示例** (Python):
```python
import requests

search_data = {
    "url": "https://www.python.org/",
    "jina_api_key": "jina_xxx",
    "user_id": "user123",
    "timeout": 30
}

response = requests.post(
    "http://localhost:8080/search",
    json=search_data
)
result = response.json()

if result["success"]:
    print(f"URL: {result['url']}")
    print(f"Content Type: {result['content_type']}")
    print(f"Content Length: {len(result['content'])}")
    print(f"\nContent Preview:\n{result['content'][:500]}...")
else:
    print(f"Error: {result.get('error')}")
```

**响应示例**:
```json
{
  "url": "https://www.python.org/",
  "content": "Welcome to Python.org\n\nPython is a programming language that lets you work quickly and integrate systems more effectively...\n\n# Latest News\n- Python 3.12 Released\n- PyCon 2026 Announced\n...",
  "status_code": 200,
  "content_type": "text/plain",
  "success": true
}
```

---

## 完整使用示例

### Python 完整示例:

```python
import requests
import json

class JinaSearchClient:
    """Jina Search Agent 客户端"""
    
    def __init__(self, base_url: str, jina_api_key: str):
        self.base_url = base_url.rstrip('/')
        self.jina_api_key = jina_api_key
    
    def health_check(self):
        """健康检查"""
        response = requests.get(f"{self.base_url}/health")
        return response.json()
    
    def get_info(self):
        """获取服务信息"""
        response = requests.get(f"{self.base_url}/")
        return response.json()
    
    def fetch_content(self, url: str, user_id: str = None, timeout: int = 30):
        """提取网页内容"""
        data = {
            "url": url,
            "jina_api_key": self.jina_api_key,
            "user_id": user_id,
            "timeout": timeout
        }
        response = requests.post(f"{self.base_url}/search", json=data)
        return response.json()


# 使用示例
client = JinaSearchClient(
    base_url="http://localhost:8080",
    jina_api_key="jina_xxx"
)

# 1. 健康检查
print("Health:", client.health_check())

# 2. 获取服务信息
print("Info:", client.get_info())

# 3. 提取网页内容
urls = [
    "https://www.python.org/",
    "https://kubernetes.io/docs/",
    "https://docs.docker.com/",
    "https://github.com/",
]

for url in urls:
    print(f"\n{'='*60}")
    print(f"Fetching: {url}")
    print('='*60)
    
    result = client.fetch_content(url, user_id="user123")
    
    if result["success"]:
        print(f"Status: {result['status_code']}")
        print(f"Content Type: {result['content_type']}")
        print(f"Content Length: {len(result['content'])} chars")
        print(f"\nContent Preview:")
        print(result['content'][:300])
        print("...")
    else:
        print(f"Error: Failed to fetch content")
```

---

### 批量内容提取:

```python
import requests
import concurrent.futures
from typing import List, Dict

def fetch_url(url: str, jina_api_key: str, user_id: str = None) -> Dict:
    """提取单个 URL 的内容"""
    try:
        response = requests.post(
            "http://localhost:8080/search",
            json={
                "url": url,
                "jina_api_key": jina_api_key,
                "user_id": user_id,
                "timeout": 30
            },
            timeout=60
        )
        result = response.json()
        return {
            "url": url,
            "success": result.get("success", False),
            "content": result.get("content", ""),
            "error": None
        }
    except Exception as e:
        return {
            "url": url,
            "success": False,
            "content": "",
            "error": str(e)
        }

# 批量提取
urls = [
    "https://www.python.org/",
    "https://www.docker.com/",
    "https://kubernetes.io/",
    "https://www.tensorflow.org/",
    "https://pytorch.org/"
]

jina_api_key = "jina_xxx"

# 并行提取
with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
    futures = [
        executor.submit(fetch_url, url, jina_api_key, f"user-{i}")
        for i, url in enumerate(urls)
    ]
    
    results = [future.result() for future in concurrent.futures.as_completed(futures)]

# 处理结果
successful = [r for r in results if r["success"]]
failed = [r for r in results if not r["success"]]

print(f"Successful: {len(successful)}/{len(urls)}")
print(f"Failed: {len(failed)}/{len(urls)}")

for result in successful:
    print(f"\n{result['url']}")
    print(f"Content length: {len(result['content'])} chars")
    print(f"Preview: {result['content'][:100]}...")
```

---

### 与 LLM 结合进行内容分析:

```python
import requests
from langchain_openai import ChatOpenAI
from langchain.prompts import PromptTemplate

class ContentAnalyzer:
    """使用 Jina 提取内容并用 LLM 分析"""
    
    def __init__(self, jina_base_url: str, jina_api_key: str, openai_api_key: str):
        self.jina_base_url = jina_base_url
        self.jina_api_key = jina_api_key
        self.llm = ChatOpenAI(
            temperature=0,
            model="gpt-3.5-turbo",
            openai_api_key=openai_api_key
        )
    
    def fetch_content(self, url: str) -> str:
        """使用 Jina 提取内容"""
        response = requests.post(
            f"{self.jina_base_url}/search",
            json={
                "url": url,
                "jina_api_key": self.jina_api_key
            }
        )
        result = response.json()
        return result.get("content", "") if result.get("success") else ""
    
    def summarize(self, url: str) -> str:
        """提取并摘要网页内容"""
        content = self.fetch_content(url)
        
        if not content:
            return "无法提取内容"
        
        prompt = PromptTemplate(
            input_variables=["content"],
            template="请用中文总结以下网页内容，保持简洁明了:\n\n{content}\n\n摘要:"
        )
        
        # 限制内容长度
        content = content[:4000]
        
        result = self.llm.invoke(prompt.format(content=content))
        return result.content
    
    def extract_key_points(self, url: str) -> List[str]:
        """提取关键要点"""
        content = self.fetch_content(url)
        
        if not content:
            return []
        
        prompt = PromptTemplate(
            input_variables=["content"],
            template="请从以下内容中提取5个关键要点，每个要点一行:\n\n{content}\n\n关键要点:"
        )
        
        content = content[:4000]
        result = self.llm.invoke(prompt.format(content=content))
        
        # 解析要点
        points = [line.strip() for line in result.content.split('\n') if line.strip()]
        return points


# 使用示例
analyzer = ContentAnalyzer(
    jina_base_url="http://localhost:8080",
    jina_api_key="jina_xxx",
    openai_api_key="sk-xxx"
)

# 摘要网页
url = "https://www.python.org/about/"
summary = analyzer.summarize(url)
print(f"URL: {url}")
print(f"Summary: {summary}")

# 提取关键要点
key_points = analyzer.extract_key_points(url)
print("\nKey Points:")
for i, point in enumerate(key_points, 1):
    print(f"{i}. {point}")
```

---

### 监控和内容变更检测:

```python
import requests
import time
import hashlib
from datetime import datetime

class ContentMonitor:
    """监控网页内容变化"""
    
    def __init__(self, jina_base_url: str, jina_api_key: str):
        self.jina_base_url = jina_base_url
        self.jina_api_key = jina_api_key
        self.cache = {}
    
    def get_content_hash(self, url: str) -> str:
        """获取内容哈希值"""
        response = requests.post(
            f"{self.jina_base_url}/search",
            json={
                "url": url,
                "jina_api_key": self.jina_api_key
            }
        )
        result = response.json()
        
        if result.get("success"):
            content = result["content"]
            return hashlib.md5(content.encode()).hexdigest()
        return ""
    
    def check_updates(self, urls: List[str]) -> Dict:
        """检查 URL 列表是否有更新"""
        updates = {}
        
        for url in urls:
            current_hash = self.get_content_hash(url)
            previous_hash = self.cache.get(url)
            
            if previous_hash is None:
                updates[url] = {"status": "new", "hash": current_hash}
            elif current_hash != previous_hash:
                updates[url] = {"status": "updated", "hash": current_hash}
            else:
                updates[url] = {"status": "unchanged", "hash": current_hash}
            
            self.cache[url] = current_hash
        
        return updates


# 使用示例
monitor = ContentMonitor(
    jina_base_url="http://localhost:8080",
    jina_api_key="jina_xxx"
)

urls_to_monitor = [
    "https://www.python.org/downloads/",
    "https://kubernetes.io/blog/",
    "https://github.com/trending"
]

# 定期检查更新
while True:
    print(f"\n[{datetime.now()}] Checking for updates...")
    updates = monitor.check_updates(urls_to_monitor)
    
    for url, info in updates.items():
        if info["status"] == "updated":
            print(f"⚠️  UPDATED: {url}")
        elif info["status"] == "new":
            print(f"🆕 NEW: {url}")
        else:
            print(f"✓ No change: {url}")
    
    # 每 5 分钟检查一次
    time.sleep(300)
```

---

## 环境变量配置

```bash
# 服务配置
export SERVICE_HOST="0.0.0.0"
export SERVICE_PORT="8080"
export POD_NAME="jina-search-agent"
export TEMPLATE_TYPE="jina_search_agent"

# Jina API (从请求传入，也可以预配置)
# export JINA_API_KEY="jina_xxx"

# 启动服务
python jina_search_agent.py
```

---

## 获取 Jina API Key

1. 访问: https://jina.ai/
2. 注册账号
3. 在控制台获取 API key
4. 免费套餐: 1,000 次请求/天

---

## 支持的网站类型

Jina Reader API 支持多种网站:
- 新闻网站
- 博客文章
- 文档网站
- GitHub 页面
- 维基百科
- 论文网站 (arXiv, etc.)

---

## 注意事项

1. **API Key**: 从请求中传入，保证安全性
2. **速率限制**: 注意 Jina API 的速率限制
3. **超时设置**: 大型网页可能需要更长时间
4. **内容格式**: 返回纯文本格式，已清理 HTML
5. **用户ID**: 可选，用于计费回调
6. **错误处理**: 检查 success 字段确认是否成功
7. **并发限制**: 建议最多 3-5 个并发请求