> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wolian.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见问题

> 花卷智能体 API 常见问题解答

## 认证相关

<AccordionGroup>
  <Accordion title="如何获取 API Key？">
    1. 访问 [Wolian AI 客户端管理](https://wolian.cc/platform/clients-management)
    2. 使用你的账户登录
    3. 点击"+ 创建"按钮创建新的客户端
    4. 确保密钥状态为"已激活"（绿色标识）
    5. 点击复制按钮，复制并安全保存 API Key

    注意：密钥仅在创建时完整显示一次，请妥善保管。
  </Accordion>

  {" "}

  <Accordion title="API Key 泄露了怎么办？">
    如果怀疑 API Key 泄露，请立即： 1. 在 [Wolian AI 平台](https://wolian.cc/platform/clients-management) 中撤销该密钥 2. 创建新的 API
    Key 并激活 3. 更新所有使用旧 Key 的应用 4. 监控账户使用情况是否异常
  </Accordion>

  <Accordion title="为什么一直返回 401 错误？">
    常见原因：

    * API Key 格式错误（检查是否包含 `Bearer` 前缀）
    * API Key 已过期或被撤销
    * 请求头中缺少 `Authorization` 字段
    * 使用了错误的环境变量名

    解决方法：

    ```bash theme={null}
    # 检查 API Key 格式
    curl -H "Authorization: Bearer YOUR_API_KEY" \
      https://huajune.duliday.com/api/v1/models
    ```
  </Accordion>
</AccordionGroup>

## 模型与工具

<AccordionGroup>
  <Accordion title="如何查看我可以使用哪些模型？">
    调用 `GET /api/v1/models` 端点：

    ```bash theme={null}
    curl -X GET https://huajune.duliday.com/api/v1/chat \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    返回你账户可访问的所有模型列表。
  </Accordion>

  <Accordion title="为什么某个模型返回 403 错误？">
    可能原因：

    * 该模型不在你的许可列表中
    * 账户权限不足
    * 模型 ID 拼写错误

    解决方法：

    1. 使用 `GET /api/v1/models` 查看可用模型
    2. 联系销售团队申请权限
    3. 检查模型 ID 是否正确（区分大小写）
  </Accordion>

  <Accordion title="如何启用工具调用？">
    在请求中添加 `allowedTools` 数组，并提供必要的上下文：

    ```json 启用工具示例 lines icon="wrench" theme={null}
    {
      "model": "anthropic/claude-3-7-sonnet-20250219",
      "messages": [
        { "role": "user", "content": "候选人问：薪资待遇怎么样？" }
      ],
      "allowedTools": ["zhipin_reply_generator"],
      "context": {
        "preferredBrand": "蜀地源冒菜",
        "configData": { ... },
        "replyPrompts": { ... }
      }
    }
    ```

    查看可用工具：

    ```bash 查看工具列表 icon="terminal" theme={null}
    curl -X GET https://huajune.duliday.com/api/v1/tools \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Accordion>

  <Accordion title="工具需要哪些上下文？">
    每个工具的 `requiredContext` 不同：

    * **zhipin\_reply\_generator**: 需要 `configData` 和 `replyPrompts` ✅ 推荐用于业务场景
    * **bash**: 需要 `sandboxId`（E2B 沙盒环境）⚠️ 一般不推荐使用

    <Tip>
      **推荐**：使用 zhipin\_reply\_generator 等业务工具，它们更贴合实际的招聘场景，无需额外的沙盒环境配置。
    </Tip>

    使用 `GET /api/v1/tools` 查看每个工具的具体要求。
  </Accordion>

  <Accordion title="工具调用是如何工作的？">
    **花卷智能体 API 采用服务端自动执行模式**，一次请求即可完成所有工具调用。

    **完整流程**：

    1. **用户发送请求**：包含 `allowedTools` 参数和必要的上下文
    2. **服务端自动处理**：
       * AI 决定需要调用工具
       * 服务端自动执行工具
       * AI 理解执行结果
       * 生成最终回复
    3. **返回完整历史**：响应包含所有中间步骤（tool-call 和 tool-result）

    ```json 请求示例 lines icon="paper-plane" theme={null}
    {
      "model": "anthropic/claude-3-7-sonnet-20250219",
      "messages": [
        { "role": "user", "content": "候选人问：薪资待遇怎么样？" }
      ],
      "allowedTools": ["zhipin_reply_generator"],
      "context": {
        "preferredBrand": "蜀地源冒菜",
        "configData": { ... },
        "replyPrompts": { ... }
      }
    }
    ```

    <Tip>
      **无需多轮请求**：服务端自动完成所有工具调用，最多可执行 30 步。
    </Tip>

    详细说明请参阅：

    * [工具调用功能文档](/features/tool-calling)
    * [消息格式](/concepts/messages)
  </Accordion>

  <Accordion title="如何查看工具执行的中间过程？">
    工具在服务端自动执行，有两种方式查看执行过程：

    **方式 1：使用流式输出（实时监控）**

    ```javascript 流式监控 lines icon="stream" theme={null}
    const response = await fetch(url, {
      body: JSON.stringify({
        stream: true,
        allowedTools: ["zhipin_reply_generator"],
        context: { ... },
        ...
      })
    });

    const reader = response.body.getReader();
    // 监听 event: tool 事件，实时查看工具调用过程
    ```

    **方式 2：检查响应中的 messages 数组（非流式）**

    ```javascript 查看完整历史 lines icon="list" theme={null}
    const data = await response.json();

    // 响应包含完整执行历史
    data.data.messages.forEach(msg => {
      msg.parts.forEach(part => {
        if (part.type === 'dynamic-tool') {
          console.log('工具调用:', part.toolName);
          console.log('输入:', part.input);
          if (part.output) {
            console.log('输出:', part.output);
          }
        }
      });
    });
    ```

    详见[工具调用 - 流式输出](/features/tool-calling#流式输出中的工具事件)
  </Accordion>
</AccordionGroup>

## 功能使用

<AccordionGroup>
  <Accordion title="流式输出和非流式输出有什么区别？">
    | 特性       | 流式 (`stream: true`) | 非流式 (`stream: false`) |
    | -------- | ------------------- | --------------------- |
    | 响应方式     | 实时逐字返回              | 一次性返回完整内容             |
    | 用户体验     | 打字机效果，感知更快          | 需要等待完整生成              |
    | 适用场景     | 聊天界面、交互应用           | 后台处理、批量任务             |
    | Token 计费 | 相同                  | 相同                    |

    推荐：面向用户的应用使用流式输出。
  </Accordion>

  <Accordion title="什么时候应该使用消息剪裁？">
    建议在以下情况启用消息剪裁：

    * 对话轮次超过 20 轮
    * 历史消息包含大量重复信息
    * 需要优化成本
    * 遇到上下文长度限制

    不建议在以下情况使用：

    * 短对话（\< 10 轮）
    * 需要完整历史信息的任务
    * 关键业务对话
  </Accordion>

  <Accordion title="如何自定义系统提示词？">
    三种方式：

    **方式 1：直接指定（推荐）**

    ```json theme={null}
    {
      "systemPrompt": "你是一个专业的Python导师"
    }
    ```

    ✅ 最简单，直接覆盖 system prompt

    **方式 2：使用 promptType + context.systemPrompts**

    ```json theme={null}
    {
      "promptType": "bossZhipinSystemPrompt",
      "context": {
        "systemPrompts": {
          "bossZhipinSystemPrompt": "你是BOSS直聘招聘助手..."
        }
      }
    }
    ```

    ✅ `promptType` 同时决定工具集和 system prompt

    ✅ 适合多场景管理

    **方式 3：使用默认值**
    不设置任何参数，使用 `"You are a helpful AI assistant."`

    详见[系统提示词文档](/concepts/system-prompts)
  </Accordion>

  <Accordion title="promptType 有什么作用？">
    `promptType` 有两个独立的作用：

    **1. 决定工具集（内置、强制）**

    * 通过内置的 `PROMPT_TOOL_MAPPING` 自动启用对应工具
    * 例如：`bossZhipinSystemPrompt` 自动启用招聘相关工具

    **2. 查找 system prompt（可选）**

    * 从 `context.systemPrompts[promptType]` 查找提示词文本
    * 如果没有提供 `context.systemPrompts`，使用默认 system prompt

    示例：

    ```json theme={null}
    {
      "promptType": "bossZhipinSystemPrompt"
      // 效果：
      // ✅ 启用招聘工具集
      // ℹ️ 使用默认 system prompt（因为没有提供 context.systemPrompts）
    }
    ```

    查询可用的 `promptType`：

    ```bash theme={null}
    curl -X GET https://huajune.duliday.com/api/v1/prompt-types \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Accordion>
</AccordionGroup>

## 性能与成本

<AccordionGroup>
  <Accordion title="如何降低 API 调用成本？">
    **立即生效的方法**：

    1. 启用消息剪裁（节省 40-70%）
    2. 使用成本更低的模型（如 Qwen Plus）
    3. 精简系统提示词
    4. 实现结果缓存

    **长期优化**：

    1. 监控 Token 使用情况
    2. 批量处理请求
    3. 仅在必要时启用工具
    4. 定期审查和优化提示词

    详见[性能优化指南](/best-practices/performance)
  </Accordion>

  <Accordion title="为什么响应很慢？">
    可能原因：

    1. 输入消息太长（检查 Token 数量）
    2. 启用了多个复杂工具
    3. 网络延迟
    4. 服务端负载高

    解决方法：

    * 启用消息剪裁
    * 减少不必要的工具
    * 使用流式输出改善用户体验
    * 检查网络连接
  </Accordion>

  <Accordion title="速率限制是多少？">
    默认限制：

    * 每秒请求数 (RPS): 10
    * 每分钟请求数 (RPM): 500
    * 并发请求数: 5

    超过限制会收到 `429 Too Many Requests` 错误。

    如需更高限额，请联系销售团队。
  </Accordion>
</AccordionGroup>

## 错误处理

<AccordionGroup>
  <Accordion title="收到 400 BadRequest 错误">
    常见原因：

    * 请求参数格式错误
    * 缺少必需的工具上下文
    * 无效的 `promptType`

    解决方法：

    1. 检查错误消息中的 `details` 字段
    2. 使用 `validateOnly: true` 预检查配置
    3. 查看 API 文档确认参数格式
  </Accordion>

  <Accordion title="收到 429 RateLimitExceeded 错误">
    说明超过了速率限制。

    解决方法：

    ```javascript theme={null}
    // 实现指数退避重试
    async function retryWithBackoff(fn, maxRetries = 3) {
      for (let i = 0; i < maxRetries; i++) {
        try {
          return await fn();
        } catch (error) {
          if (error.statusCode === 429 && i < maxRetries - 1) {
            const delay = Math.pow(2, i) * 1000;
            await sleep(delay);
            continue;
          }
          throw error;
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="如何追踪和报告问题？">
    每个响应都包含 `correlationId`：

    ```javascript theme={null}
    const data = await response.json();
    console.log('Correlation ID:', data.correlationId);
    ```

    向技术支持报告问题时，请提供：

    1. correlationId
    2. 请求时间
    3. 错误消息
    4. 请求参数（不要包含 API Key）
  </Accordion>
</AccordionGroup>

## 集成与开发

<AccordionGroup>
  <Accordion title="支持哪些编程语言？">
    花卷智能体 API 是标准的 REST API，支持所有能发送 HTTP 请求的编程语言：

    * JavaScript/TypeScript (Node.js, Browser)
    * Python
    * Java
    * Go
    * Ruby
    * PHP
    * C#/.NET
    * 等等...

    文档中提供了 JavaScript 和 Python 的详细示例。
  </Accordion>

  <Accordion title="如何在 React 中集成？">
    推荐使用流式输出：

    ```jsx theme={null}
    function ChatBox() {
      const [messages, setMessages] = useState([]);

      const sendMessage = async (text) => {
        const response = await fetch('https://huajune.duliday.com/api/v1/chat', {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            model: 'anthropic/claude-3-7-sonnet-20250219',
            messages: [...messages, { role: 'user', content: text }],
            stream: true
          })
        });

        const reader = response.body.getReader();
        // 处理流式响应...
      };

      return <div>{/* UI 组件 */}</div>;
    }
    ```

    详见[流式输出功能](/features/streaming)
  </Accordion>

  <Accordion title="如何处理长时间运行的请求？">
    建议：

    1. 使用流式输出，可以实时看到进度
    2. 设置合理的超时时间（建议 60-120 秒）
    3. 实现重试机制
    4. 向用户显示加载状态

    ```javascript theme={null}
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 120000); // 120秒

    try {
      const response = await fetch(url, {
        signal: controller.abort,
        ...options
      });
    } finally {
      clearTimeout(timeoutId);
    }
    ```
  </Accordion>
</AccordionGroup>

## 还有问题？

<CardGroup cols={2}>
  <Card title="查看 API 文档" icon="book" href="/api-reference/introduction">
    完整的 API 端点参考文档
  </Card>

  {" "}

  <Card title="联系技术支持" icon="headset" href="mailto:support@huajune.com">
    发送邮件获取人工支持
  </Card>

  {" "}

  <Card title="调试指南" icon="bug" href="/best-practices/debugging">
    学习调试技巧和工具
  </Card>

  <Card title="性能优化" icon="gauge-high" href="/best-practices/performance">
    优化 API 调用性能和成本
  </Card>
</CardGroup>