自定义端点

本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。

• moderation 敏感内容审计
• external_data_tool 外部数据工具

​

API 规范

POST {Your-API-Endpoint}

​

Header

​

Request Body

{
    "point":  string, //  扩展点，不同模块可能包含多个扩展点
    "params": {
        ...  // 各模块扩展点传入参数
    }
}

​

API 返回

{
    ...  // API 返回的内容，不同扩展点返回见不同模块的规范设计
}

​

校验

​

Header

Content-Type: application/json
Authorization: Bearer {api_key}

​

Request Body

{
    "point": "ping"
}

​

API 期望返回

{
    "result": "pong"
}

​

范例

​

API 范例

POST https://fake-domain.com/api/dify/receive

Content-Type: application/json
Authorization: Bearer 123456

{
    "point": "app.external_data_tool.query",
    "params": {
        "app_id": "61248ab4-1125-45be-ae32-0ce91334d021",
        "tool_variable": "weather_retrieve",
        "inputs": {
            "location": "London"
        },
        "query": "How's the weather today?"
    }
}

{
    "result": "City: London\nTemperature: 10°C\nRealFeel®: 8°C\nAir Quality: Poor\nWind Direction: ENE\nWind Speed: 8 km/h\nWind Gusts: 14 km/h\nPrecipitation: Light rain"
}

​

代码范例

1. 安装依赖
   pip install fastapi[all] uvicorn
   
2. 按照接口规范编写代码
   from fastapi import FastAPI, Body, HTTPException, Header
   from pydantic import BaseModel
   
   app = FastAPI()
   
   
   class InputData(BaseModel):
       point: str
       params: dict = {}
   
   
   @app.post("/api/dify/receive")
   async def dify_receive(data: InputData = Body(...), authorization: str = Header(None)):
       """
       Receive API query data from Dify.
       """
       expected_api_key = "123456"  # TODO Your API key of this API
       auth_scheme, _, api_key = authorization.partition(' ')
   
       if auth_scheme.lower() != "bearer" or api_key != expected_api_key:
           raise HTTPException(status_code=401, detail="Unauthorized")
   
       point = data.point
   
       # for debug
       print(f"point: {point}")
   
       if point == "ping":
           return {
               "result": "pong"
           }
       if point == "app.external_data_tool.query":
           return handle_app_external_data_tool_query(params=data.params)
       # elif point == "{point name}":
           # TODO other point implementation here
   
       raise HTTPException(status_code=400, detail="Not implemented")
   
   
   def handle_app_external_data_tool_query(params: dict):
       app_id = params.get("app_id")
       tool_variable = params.get("tool_variable")
       inputs = params.get("inputs")
       query = params.get("query")
   
       # for debug
       print(f"app_id: {app_id}")
       print(f"tool_variable: {tool_variable}")
       print(f"inputs: {inputs}")
       print(f"query: {query}")
   
       # TODO your external data tool query implementation here, 
       #  return must be a dict with key "result", and the value is the query result
       if inputs.get("location") == "London":
           return {
               "result": "City: London\nTemperature: 10°C\nRealFeel®: 8°C\nAir Quality: Poor\nWind Direction: ENE\nWind "
                         "Speed: 8 km/h\nWind Gusts: 14 km/h\nPrecipitation: Light rain"
           }
       else:
           return {"result": "Unknown city"}
   
3. 启动 API 服务，默认端口为 8000，API 完整地址为：http://127.0.0.1:8000/api/dify/receive，配置的 API Key 为 123456。
   uvicorn main:app --reload --host 0.0.0.0
   
4. 在 Dify 配置该 API。
5. 在 App 中选择该自定义端点。

{
    "point": "app.external_data_tool.query",
    "params": {
        "app_id": "61248ab4-1125-45be-ae32-0ce91334d021",
        "tool_variable": "weather_retrieve",
        "inputs": {
            "location": "London"
        },
        "query": "How's the weather today?"
    }
}

{
    "result": "City: London\nTemperature: 10°C\nRealFeel®: 8°C\nAir Quality: Poor\nWind Direction: ENE\nWind Speed: 8 km/h\nWind Gusts: 14 km/h\nPrecipitation: Light rain"
}

​

本地调试

1. 进入 https://ngrok.com 官网，注册并下载 Ngrok 文件。
   
2. 下载完成后，进入下载目录，根据下方说明解压压缩包，并执行说明中的初始化脚本。
   unzip /path/to/ngrok.zip
   ./ngrok config add-authtoken 你的 Token
   
3. 查看本地 API 服务的端口：
   
   并运行以下命令启动：
   ./ngrok http 端口号
   
   启动成功的样例如下：
   
4. 我们找到 Forwarding 中，如上图：https://177e-159-223-41-52.ngrok-free.app（此为示例域名，请替换为自己的）即为公网域名。

​

使用 Cloudflare Workers 部署自定义端点