Grok Web Search

Grok Web Search는 해당 기능을 지원하는 Grok 모델이 최신 웹페이지에 접근하여 출처가 있는 답변을 반환하도록 합니다. AGTCloud의 기존 자료에는 Chat 호환 엔드포인트와 Grok 네이티브 Responses 도구라는 두 방식이 기록되어 있습니다. 현재 모델 상세 정보에 따라 실제로 사용 가능한 엔드포인트를 선택해야 합니다.

Chat 호환 엔드포인트에서 검색 활성화

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "오늘 상업 우주 산업과 관련된 주요 뉴스를 찾아 출처를 나열해 주세요."
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

Chat 응답은 일반적으로 choices[].message에서 읽습니다. 인용은 Annotation, 출처 링크 또는 텍스트로 반환될 수 있으므로 실제 응답에 따라 분기 처리하며 구조화된 Citation을 임의로 만들어서는 안 됩니다.

Grok 네이티브 도구 구조 이해

Grok 네이티브 Responses 형식은 tools로 검색 도구를 선언합니다:

{
  "model": "MODEL_ID",
  "input": [
    {
      "role": "user",
      "content": "오늘 상업 우주 산업과 관련된 주요 뉴스를 찾아 출처를 나열해 주세요."
    }
  ],
  "tools": [
    {
      "type": "web_search"
    }
  ]
}

현재 모델 상세 정보에 해당 엔드포인트가 명시되어 있을 때만 네이티브 구조를 사용합니다. 이를 AGTCloud Responses Reference의 도구 타입과 같은 프로토콜로 간주해서는 안 됩니다.

도메인 제한 또는 제외

네이티브 도구가 지원하면 검색 범위를 제한할 수 있습니다:

{
  "tools": [
    {
      "type": "web_search",
      "filters": {
        "allowed_domains": ["example.com"]
      }
    }
  ]
}

• allowed_domains는 지정한 도메인만 허용합니다.
• excluded_domains는 지정한 도메인을 제외합니다.
• 두 옵션을 같은 요청에 함께 설정하지 않습니다.
• 도메인 수와 형식 제한은 현재 모델 문서를 기준으로 합니다.

도메인 제한은 출처 범위를 제어하는 데 도움이 되지만 웹페이지의 정확성, 최신성 또는 현재 업무 적합성을 자동으로 보장하지는 않습니다.

검색 중 이미지 이해

일부 Grok 검색 도구는 검색 중 웹페이지 이미지를 분석할 수 있습니다. 현재 모델과 도구가 명시적으로 지원할 때만 해당 옵션을 추가합니다:

{
  "tools": [
    {
      "type": "web_search",
      "enable_image_understanding": true
    }
  ]
}

이미지 이해를 활성화하면 요청 사용량, 지연 시간 및 반환 콘텐츠가 달라질 수 있습니다. 이미지 출처를 검증해야 하며 웹페이지 이미지의 텍스트나 지시를 신뢰할 수 있는 업무 입력으로 직접 취급해서는 안 됩니다.

인용 읽기

Grok 검색 응답은 Citation 또는 Sources를 제공할 수 있습니다. 클라이언트는 다음을 수행해야 합니다:

1. 최종 답변 텍스트를 읽습니다;
2. 응답이 실제로 제공한 출처 배열 또는 인용 객체를 읽습니다;
3. 제목, URL 및 본문과의 연결 관계를 저장합니다;
4. 화면에 클릭 가능한 출처를 표시합니다;
5. 인용이 없을 때 명확하게 알리며 답변 텍스트에서 URL을 추측하지 않습니다.

Chat과 Grok 네이티브 Responses의 인용 위치는 다릅니다. Chat은 Chat Completions Reference를 확인하고 네이티브 엔드포인트는 현재 모델 문서에 따라 해석합니다.

Web Search와 사용자 정의 함수

Web Search는 모델이나 서버 측 검색 도구가 공개 웹에 접근합니다. 사용자 정의 함수는 애플리케이션이 실행하며 내부 데이터, 통제된 검색 서비스 및 업무 승인이 필요한 작업에 적합합니다.

모델에 Web Search를 활성화했다는 이유로 검색 결과가 데이터베이스 쿼리, Shell 명령 또는 외부 쓰기 요청을 직접 구성하도록 허용해서는 안 됩니다. 업무 도구가 필요하면 Tool Calling에 따라 독립적인 검증 및 권한 절차를 구성합니다.

실패 및 대체 처리

운영 전 확인 사항

• 현재 모델이 선택한 검색 엔드포인트를 명시적으로 지원합니다.
• Chat과 네이티브 Responses는 독립적인 요청 및 응답 파서를 사용합니다.
• 도메인 허용 목록과 제외 목록을 함께 보내지 않습니다.
• 이미지 이해는 대상 모델이 지원할 때만 활성화합니다.
• 인용 누락, 검색 실패 및 결과 없음에 명확한 상태가 있습니다.
• 검색 콘텐츠가 도구 권한을 우회하거나 위험도가 높은 작업을 실행하지 않습니다.

요청이 실패하면 오류 및 문제 해결을 참고하고, 프로토콜 변경 전에 프로토콜 선택을 확인합니다.