Skip to main content
工具調用

圖搜圖

圖搜圖工具使模型能夠根據輸入圖片從互連網搜尋視覺相似的圖片,並基於搜尋結果進行分析和推理,適用於以圖找同款、視覺內容溯源等情境。

使用方式

圖搜圖功能通過 Responses API 呼叫。您需要在 tools 參數中添加 image_search 工具,並在 input 中以多模態格式傳入圖片。
input 中必須包含圖片內容,通過 input_image 類型傳入圖片 URL。可同時傳入 input_text 類型的文本,為搜尋提供補充說明。
# 匯入依賴與建立用戶端...
input_content = [
    {"type": "input_text", "text": "找與這張圖相似風格的風景圖"},
    {"type": "input_image", "image_url": "https://img.alicdn.com/imgextra/i4/O1CN01YbrnSS1qtmsAkw0Ud_!!6000000005554-2-tps-788-450.png"}
]
response = client.responses.create(
    model="qwen3.8-max",
    input=[{"role": "user", "content": input_content}],
    tools=[{"type": "image_search"}]
)

print(response.output_text)

支援的模型

推薦模型

為獲得最佳工具調用效果,推薦使用以下模型: 千問Plus:Qwen3.7-Plus系列、Qwen3.6-Plus系列、Qwen3.5-Plus系列 千問Max:Qwen3.8-Max系列、qwen3.7-max-2026-06-08 qwen3.8-27b

其他模型

以下模型也支援此工具調用,但效果不如推薦模型。
  • 千問Flash:Qwen3.7-Flash系列、Qwen3.6-Flash系列、Qwen3.5-Flash系列
僅支援通過 Responses API 呼叫。

快速開始

運行以下代碼,通過 Responses API 呼叫圖搜圖工具,根據輸入的圖片搜尋相似或相關圖片。
需要已擷取與配置 API Key配置API Key到環境變數
請將範例程式碼中的 image_url 替換為可公網訪問的圖片 URL。
import os
import json
from openai import OpenAI

client = OpenAI(
    # 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡地區的URL,調用時請將 {WorkspaceId} 替換為真實的業務空間ID,各地區的URL不同。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

input_content = [
    {"type": "input_text", "text": "找與這張圖相似風格的風景圖"},
    # 請將 image_url 替換為實際的圖片公網 URL
    {"type": "input_image", "image_url": "https://img.alicdn.com/imgextra/i4/O1CN01YbrnSS1qtmsAkw0Ud_!!6000000005554-2-tps-788-450.png"}
]

response = client.responses.create(
    model="qwen3.8-max",
    input=[{"role": "user", "content": input_content}],
    tools=[
        {
            "type": "image_search"
        }
    ]
)

# 遍曆 output 展示每個步驟
for item in response.output:
    if item.type == "image_search_call":
        print(f"[工具調用] 圖搜圖 (status: {item.status})")
        # 解析並展示搜尋到的圖片列表
        if item.output:
            images = json.loads(item.output)
            print(f"  搜尋到 {len(images)} 張圖片:")
            for img in images[:5]:  # 展示前5張
                print(f"  [{img['index']}] {img['title']}")
                print(f"      {img['url']}")
            if len(images) > 5:
                print(f"  ... 共 {len(images)} 張圖片")
    elif item.type == "message":
        print(f"\n[模型回複]")
        print(response.output_text)

# 展示 Token 用量和工具調用統計
print(f"\n[Token 用量] 輸入: {response.usage.input_tokens}, 輸出: {response.usage.output_tokens}, 合計: {response.usage.total_tokens}")
if hasattr(response.usage, 'x_tools') and response.usage.x_tools:
    for tool_name, info in response.usage.x_tools.items():
        print(f"[工具統計] {tool_name} 調用次數: {info.get('count', 0)}")
運行以上代碼可擷取如下回複:
[工具調用] 圖搜圖 (status: completed)
  搜尋到 2 張圖片:
  [1] QingMing Festival Holiday Notice 2024
      https://www.healthcabin.net/blog/wp-content/uploads/2024/04/QingMing-Festival-Holiday-Notice-2024.jpg
  [2] Serene Asian Landscape Stone Bridge Reflecting in Misty Water
      https://thumbs.dreamstime.com/b/serene-asian-landscape-stone-bridge-reflecting-misty-water-tranquil-illustration-traditional-arch-spanning-lake-style-376972039.jpg

[模型回複]
好的,已經為您找到了幾張風格相似的風景圖。

這些圖片都展現了典型的中國水墨畫或傳統山水畫的意境,具有以下幾個共同點:
*   **傳統建築**:如亭台樓閣、拱橋等。
*   **自然元素**:如遠山、湖泊、垂柳、荷花等。
*   **藝術風格**:採用淡雅的色彩和柔和的線條,營造出寧靜、悠遠的氛圍。

...

[Token 用量] 輸入: 2753, 輸出: 181, 合計: 2934
[工具統計] image_search 調用次數: 1

流式輸出

運行圖搜圖工具需要較長處理時間,建議啟用流式輸出,即時擷取中間過程輸出結果。
import os
import json
from openai import OpenAI

client = OpenAI(
    # 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡地區的URL,調用時請將 {WorkspaceId} 替換為真實的業務空間ID,各地區的URL不同。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

input_content = [
    {"type": "input_text", "text": "找與這張圖相似風格的風景圖"},
    # 請將 image_url 替換為實際的圖片公網 URL
    {"type": "input_image", "image_url": "https://img.alicdn.com/imgextra/i4/O1CN01YbrnSS1qtmsAkw0Ud_!!6000000005554-2-tps-788-450.png"}
]

stream = client.responses.create(
    model="qwen3.8-max",
    input=[{"role": "user", "content": input_content}],
    tools=[{"type": "image_search"}],
    stream=True
)

for event in stream:
    # 工具調用開始
    if event.type == "response.output_item.added":
        if event.item.type == "image_search_call":
            print("[工具調用] 圖搜圖搜尋中...")
    # 工具調用完成,解析並展示搜尋到的圖片列表
    elif event.type == "response.output_item.done":
        if event.item.type == "image_search_call":
            print(f"[工具調用] 圖搜圖完成 (status: {event.item.status})")
            if event.item.output:
                images = json.loads(event.item.output)
                print(f"  搜尋到 {len(images)} 張圖片:")
                for img in images[:5]:  # 展示前5張
                    print(f"  [{img['index']}] {img['title']}")
                    print(f"      {img['url']}")
                if len(images) > 5:
                    print(f"  ... 共 {len(images)} 張圖片")
    # 模型回複開始
    elif event.type == "response.content_part.added":
        print(f"\n[模型回複]")
    # 流式文本輸出
    elif event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    # 響應完成,輸出用量
    elif event.type == "response.completed":
        usage = event.response.usage
        print(f"\n\n[Token 用量] 輸入: {usage.input_tokens}, 輸出: {usage.output_tokens}, 合計: {usage.total_tokens}")
        if hasattr(usage, 'x_tools') and usage.x_tools:
            for tool_name, info in usage.x_tools.items():
                print(f"[工具統計] {tool_name} 調用次數: {info.get('count', 0)}")
運行以上代碼可擷取如下回複:
[工具調用] 圖搜圖搜尋中...
[工具調用] 圖搜圖完成 (status: completed)
  搜尋到 3 張圖片:
  [1] QingMing Festival Holiday Notice 2024
      https://www.healthcabin.net/blog/wp-content/uploads/2024/04/QingMing-Festival-Holiday-Notice-2024.jpg
  [2] Serene Asian Landscape Stone Bridge Reflecting in Misty Water
      https://thumbs.dreamstime.com/b/serene-asian-landscape-stone-bridge-reflecting-misty-water-...
  [3] ...

[模型回複]
好的,已經為您找到了幾張風格相似的風景圖。這些圖片都展現了典型的中國水墨畫或工筆畫風格...

[Token 用量] 輸入: 5339, 輸出: 164, 合計: 5503
[工具統計] image_search 調用次數: 1

計費說明

計費涉及以下方面:
  • 模型調用費用:圖片搜尋的結果資訊會拼接到提示詞中,增加模型的輸入 Token,按照模型的標準價格計費。價格詳情請參考百鍊控制台。
  • 工具調用費用:每1000次調用收費:新加坡地區為$8,華北2(北京)地區為$6.881。

常見問題

Q:支援的圖片格式有哪些?支援哪些圖片傳入方式?

A:請參見:映像與視頻理解檔案傳入方式
OpenAI SDK 不支援本地路徑傳入。

Q:支援傳入幾張圖片?

A:圖片數量受模型最大輸入長度限制:圖片和文本的總 Token 數需小於模型支援的最大值。模型每次僅搜尋一張圖片,但可多次調用以處理多張。
搜尋圖片的數量由模型決策。

Q:會返回幾張搜尋圖片結果?

A:由模型決策,數量不固定,最多不超過 100 張。
Token Plan
模型體驗
用量統計與效能監控
資產中心
服務支援
圖搜圖 - Alibaba Cloud Model Studio