# 统一模型调用指南

## 概述

本项目采用统一的模型配置管理，所有模型配置集中存储在 `model_setting.yaml` 中，通过 `model_config_loader.py` 提供统一接口。

## 配置文件结构

### model_setting.yaml

```yaml
# 可用模型列表（必须与 model_handler.py 中的模型类型名称一致）
available_models:
  - qwen3_5_35b_a3b        # DashScope Qwen3.5-35B-A3B
  - shutian_qwen3_5_35b    # 蜀天Qwen3.5-35B
  - shutian_qwen3_5_122b   # 蜀天Qwen3.5-122B
  - lq_qwen3_8b_emd        # 本地Embedding模型

# 功能模块模型配置
model_settings:
  # 文档分类 - 二级分类
  doc_classification_secondary:
    model: shutian_qwen3_5_35b
    enable_thinking: false
    description: "文档二级分类，蜀天35B"

  # 文档分类 - 三级分类
  doc_classification_tertiary:
    model: shutian_qwen3_5_35b
    enable_thinking: false
    description: "文档三级分类，蜀天35B"

  # 完整性审查 - 内容生成
  completeness_review_generate:
    model: shutian_qwen3_5_122b
    enable_thinking: true
    description: "完整性审查内容生成，蜀天122B详细推理"

  # 敏感信息检查
  sensitive_check:
    model: shutian_qwen3_5_35b
    enable_thinking: false
    description: "敏感信息快速检查，蜀天35B"

  # ... 其他功能配置

# 默认配置（当功能未指定时使用）
default:
  model: shutian_qwen3_5_35b
  enable_thinking: false
```

## 模型调用方式

### 方式一：使用 function_name（推荐）

通过功能名称自动从 `model_setting.yaml` 加载对应的模型和 thinking 模式。

```python
from foundation.ai.agent.generate.model_generate import generate_model_client

# 调用模型，自动加载 doc_classification_tertiary 配置的模型
response = await generate_model_client.get_model_generate_invoke(
    trace_id="my_trace_id",
    system_prompt="你是专家",
    user_prompt="请分析...",
    function_name="doc_classification_tertiary"  # 功能名称
)
```

**适用场景**：业务功能调用，如分类、审查等。

### 方式二：使用 model_name

直接指定模型名称，跳过 `model_setting.yaml` 配置。

```python
from foundation.ai.agent.generate.model_generate import generate_model_client

# 直接指定模型
response = await generate_model_client.get_model_generate_invoke(
    trace_id="my_trace_id",
    system_prompt="你是专家",
    user_prompt="请分析...",
    model_name="shutian_qwen3_5_122b"  # 直接指定模型
)
```

**适用场景**：需要临时切换模型，或测试特定模型性能。

### 方式三：使用 model_handler

通过 `model_handler` 获取模型实例，进行更底层的操作。

```python
from foundation.ai.models.model_handler import model_handler

# 根据功能名称获取模型
model = model_handler.get_model_by_function("doc_classification_tertiary")

# 或根据模型名称获取
model = model_handler.get_model_by_name("shutian_qwen3_5_35b")

# 调用模型
response = await model.ainvoke(messages)
```

**适用场景**：需要自定义调用逻辑，或集成到现有框架。

### 方式四：流式调用

使用流式输出生成文本。

```python
from foundation.ai.agent.generate.model_generate import generate_model_client

# 流式调用（使用 function_name）
for chunk in generate_model_client.get_model_generate_stream(
    trace_id="my_trace_id",
    messages=messages,
    function_name="rag_answer_generate"
):
    yield chunk
```

**适用场景**：实时响应场景，如聊天、长文本生成。

## 配置加载接口

### 获取模型配置

```python
from foundation.ai.models.model_config_loader import (
    get_model_for_function,
    get_thinking_mode_for_function,
    get_full_config_for_function
)

# 获取指定功能的模型名称
model_name = get_model_for_function("doc_classification_tertiary")
# 返回: "shutian_qwen3_5_35b"

# 获取指定功能的 thinking 模式
thinking = get_thinking_mode_for_function("doc_classification_tertiary")
# 返回: False

# 获取完整配置
config = get_full_config_for_function("doc_classification_tertiary")
# 返回: ModelFunctionConfig(model="shutian_qwen3_5_35b", enable_thinking=False, description="...")
```

### 获取默认配置

```python
from foundation.ai.models.model_config_loader import get_model_for_function

# 获取默认模型（当功能未指定时使用）
default_model = get_model_for_function("default")
# 返回: "shutian_qwen3_5_35b"
```

## 功能名称列表

| 功能名称 | 说明 | 默认模型 |
|---------|------|---------|
| `doc_classification_secondary` | 文档二级分类 | shutian_qwen3_5_35b |
| `doc_classification_tertiary` | 文档三级分类 | shutian_qwen3_5_35b |
| `doc_classification_tertiary_complex` | 三级分类-复杂段落 | shutian_qwen3_5_122b |
| `completeness_review_generate` | 完整性审查-生成 | shutian_qwen3_5_122b |
| `completeness_review_classify` | 完整性审查-分类 | shutian_qwen3_5_35b |
| `rag_query_understand` | RAG查询理解 | shutian_qwen3_5_35b |
| `rag_answer_generate` | RAG答案生成 | shutian_qwen3_5_122b |
| `sensitive_check` | 敏感信息检查 | shutian_qwen3_5_35b |
| `grammar_check` | 语法检查 | shutian_qwen3_5_35b |
| `timeliness_review` | 时效性审查 | shutian_qwen3_5_35b |
| `reference_review` | 规范性审查 | shutian_qwen3_5_35b |
| `directory_extraction` | 目录提取 | shutian_qwen3_5_35b |
| `default` | 默认兜底配置 | shutian_qwen3_5_35b |

## 迁移指南

### 从旧代码迁移

**旧代码（硬编码模型）：**
```python
# 不推荐：硬编码模型名称
response = await model_client.get_model_generate_invoke(
    trace_id="xxx",
    messages=messages,
    model_name="qwen3_30b"  # 硬编码
)
```

**新代码（使用配置）：**
```python
# 推荐：使用 function_name 从配置加载
response = await model_client.get_model_generate_invoke(
    trace_id="xxx",
    messages=messages,
    function_name="completeness_review_classify"  # 从配置加载
)
```

### 新增功能配置步骤

1. **在 `model_setting.yaml` 中添加配置：**

```yaml
model_settings:
  # 新功能配置
  my_new_feature:
    model: shutian_qwen3_5_35b
    enable_thinking: false
    description: "新功能描述"
```

2. **在代码中使用：**

```python
response = await generate_model_client.get_model_generate_invoke(
    trace_id="xxx",
    messages=messages,
    function_name="my_new_feature"
)
```

## 注意事项

1. **优先使用 `function_name`**：便于统一管理和调整模型配置
2. **不要随意修改 `available_models`**：必须与 `model_handler.py` 中的模型类型名称一致
3. **保留 `default` 配置**：作为兜底方案，防止功能未指定时出错
4. **thinking 模式**：仅对 Qwen3.5 系列模型有效，其他模型自动忽略

## 故障排查

### 模型加载失败

检查日志：
```
[模型调用] 加载功能配置失败 [xxx]: ...
```

解决方案：
1. 检查 `model_setting.yaml` 是否存在
2. 检查功能名称是否拼写正确
3. 检查配置的模型是否在 `available_models` 列表中

### 配置未生效

检查代码是否正确传入了 `function_name`，而不是硬编码 `model_name`。

## 相关文件

- `config/model_setting.yaml` - 模型配置文件
- `config/model_config_loader.py` - 配置加载接口
- `foundation/ai/models/model_handler.py` - 模型管理器
- `foundation/ai/agent/generate/model_generate.py` - 模型调用客户端