# 高级功能

## 自定义 LLM 模型

默认情况下，SDK 使用环境变量中配置的 LLM 模型。你可以自定义 LLM 模型以获得更好的参数构建效果。

### 使用自定义模型

```python
from hezor_common.utilities.agentic.deps import OpenAIChat
from hezor_common.transfer.datahub_sdk import DatahubSDK

# 创建自定义 LLM 模型
model = OpenAIChat(
    id="gpt-4",
    api_key="your-openai-key",
    base_url="https://api.openai.com/v1"
)

# 使用自定义模型
async with DatahubSDK(model=model) as sdk:
    result = await sdk.make_call(
        query="复杂查询",
        context="详细的查询上下文"
    )
```

### 模型配置选项

```python
model = OpenAIChat(
    id="gpt-4o",
    api_key="sk-...",
    base_url="https://api.openai.com/v1",
    # 其他可选参数...
)
```

## Agent 调试模式

启用调试模式可以查看 Agent 构建参数的详细过程。

```python
async with DatahubSDK() as sdk:
    result = await sdk.make_call(
        query="query_name",
        context="context info",
        agent_kwargs={"debug_mode": True}  # 开启调试模式
    )
```

调试模式会输出：
- Agent 的推理过程
- 构建的参数
- 参数验证结果
- 重试信息

## 自定义超时和重试

### 自定义超时

```python
async with DatahubSDK(timeout=60.0) as sdk:  # 60 秒超时
    result = await sdk.make_call("query")
```

### 自定义重试次数

```python
async with DatahubSDK() as sdk:
    result = await sdk.make_call(
        query="query",
        max_retries=5  # 失败时最多重试 5 次
    )
```

### 工作流程级别的重试

`make_call()` 的 `max_retries` 控制整个工作流程的重试：

```python
# 每次重试都会重新执行：搜索 → 构建参数 → 执行
result = await sdk.make_call(
    query="query",
    max_retries=3  # 整个流程最多重试 3 次
)
```

### 参数构建级别的重试

`build_args()` 的 `max_retries` 控制参数构建的重试：

```python
args = await sdk.build_args(
    search_response=search_resp,
    args_fill_tips="tips",
    max_retries=3  # 参数验证失败时最多重试 3 次
)
```

## 构建工具函数

动态生成 Python 函数，可以像普通函数一样调用工具。

### 基本用法

```python
async with DatahubSDK() as sdk:
    # 搜索工具
    search_resp = await sdk.search_tools("天气查询")
    
    # 构建工具函数
    funcs = sdk.build_tool_functions(search_resp)
    
    # 直接调用（异步函数）
    result = await funcs["get_weather"](city="Beijing", date="2024-01-25")
    print(result.data)
```

### 使用场景

- 需要在代码中多次调用同一个工具
- 需要将工具集成到现有的代码流程中
- 需要提供类型提示和自动补全

## Model kwargs 自定义

传递额外的参数给 LLM 模型。

```python
async with DatahubSDK() as sdk:
    result = await sdk.make_call(
        query="query",
        model_kwargs={
            "temperature": 0.7,
            "max_tokens": 1000,
            # 其他模型参数...
        }
    )
```

## 自定义 API 基础 URL

连接到不同的 DataHub 实例。

```python
async with DatahubSDK(
    base_url="http://custom-datahub.example.com:12580"
) as sdk:
    result = await sdk.make_call("query")
```

## 自定义 MetaInfo 过期时间

控制 JWT Token 的有效期。

```python
from hezor_common.transfer.datahub_sdk import MetaInfo

meta_info = MetaInfo(...)

async with DatahubSDK(
    meta_info=meta_info,
    private_key_path="private_key.pem",
    password=b"password",
    meta_info_expires_in=7200  # 2 小时
) as sdk:
    result = await sdk.make_call("query")
```

## 完整的自定义配置示例

```python
from hezor_common.utilities.agentic.deps import OpenAIChat
from hezor_common.transfer.datahub_sdk import DatahubSDK, MetaInfo

# 自定义 LLM
model = OpenAIChat(
    id="gpt-4",
    api_key="sk-...",
    base_url="https://api.openai.com/v1"
)

# 自定义 MetaInfo
meta_info = MetaInfo(
    caller_id="user_123",
    subject="测试主体",
    subject_code="test_001",
    creation_name="测试模型",
    creation_slug="test_model",
    data_coverage="20240101-20241231"
)

# 创建完全自定义的 SDK 实例
async with DatahubSDK(
    base_url="http://custom-datahub.com:12580",
    timeout=60.0,
    api_key="custom-api-key",
    meta_info=meta_info,
    private_key_path="private_key.pem",
    password=b"password",
    meta_info_expires_in=7200,
    model=model
) as sdk:
    result = await sdk.make_call(
        query="complex_query",
        context="detailed context",
        max_retries=5,
        model_kwargs={"temperature": 0.7},
        agent_kwargs={"debug_mode": True}
    )
```

## 下一步

- 📚 [API 参考](api_reference.md) - 完整的方法文档
- 💡 [最佳实践](best_practices.md) - 开发建议和常见问题
