> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/kr/api/standard-package/api-v2-v3.md). # 채팅 API v2에서 v3로 마이그레이션 Chat API v3는 새 통합에 권장되는 현재 버전입니다. v2를 사용하는 기존 통합은 계속 레거시 엔드포인트를 사용할 수 있지만, 최신 카테고리 분류 체계, 심각도 모델, 응답 구조를 사용하려면 v3로 마이그레이션하는 것을 권장합니다. ### 엔드포인트 변경 요청 URL을 v2 엔드포인트에서 v3 엔드포인트로 업데이트하세요. | 버전 | 엔드포인트 | | ------ | ----------------------- | | v2 레거시 | `POST /chat/v2/message` | | v3 현재 | `POST /chat/v3/message` | 기본 URL은 동일합니다: ``` https://api.ggwp.com ``` ### 요청 본문 호환성 핵심 요청 본문은 변경되지 않았습니다. 계속해서 동일한 필수 필드를 보낼 수 있습니다: ```json { "session_id": "match_7765", "message": "좆같은 멍청이들이 어디에나 있다", "user_id": "user989" } ``` 다음의 선택적 필드도 여전히 지원됩니다: * `username` * `timestamp` * `language` * `message_index` * `message_url` * `metadata` ### 구성 변경 다음을 사용하여 요청별 구성을 전달하는 경우: `x-api-config` 헤더를 사용한다면 구성 키를 v3 카테고리 이름으로 업데이트하세요. | v2 구성 키 | v3 구성 키 | | --------------- | ---------------------- | | `identity_hate` | `identity_harm` | | `profanity` | `offensive_language` | | `link_sharing` | `links` | | `self_harm` | `self_harm_incitement` | | `age_concern` | `age_disclosure` | v3에는 다음을 포함한 추가 카테고리도 도입됩니다: * `extremism` * `gameplay_criticism` * `real_threat` * `sexual_harassment` * `sexual_violence` v3에서는 대부분의 카테고리가 동일한 민감도 등급을 지원합니다: ``` off, low, medium, high ``` 민감도는 차단되는 심각도 수준을 제어합니다:
민감도동작
off해당 카테고리를 필터링하지 않음
low심각도가 높은 콘텐츠만 필터링
medium중간 및 높은 심각도의 콘텐츠를 필터링
high낮음, 중간, 높음 심각도의 콘텐츠를 모두 필터링
> 참고: v3는 카테고리 전반에서 심각도 기반 민감도를 더 일관되게 사용합니다. 이전에 on을 사용하던 일부 v2 카테고리, 예를 들면 `on` / `off`과 같은 `drugs`, `spam`, `scam`및 `solicitation`은 이제 `off`, `low`, `medium`또는 `high`. ### 기본 구성 변경 다음을 전달하지 않거나 `x-api-config` 헤더를 전달하지 않거나 계정에 맞춤 온보딩 시점 설정이 구성되어 있지 않으면, v3는 v2와 다른 기본 필터링 동작을 적용할 수 있습니다. v2에서는 일부 카테고리가 기본적으로 비활성화되거나 더 낮은 민감도로 설정되어 있었습니다. 예를 들면: ```json { "solicitation": "off", "scam": "off", "age_concern": "off", "minor_safety": "low", "pii": "medium" } ``` 이 문서에 표시된 v3 기본 구성은 지원되는 모든 카테고리를 다음으로 설정합니다 `high` 민감도: ```json { "age_disclosure": "high", "drugs": "high", "extremism": "high", "gameplay_criticism": "high", "identity_harm": "high", "links": "high", "minor_safety": "high", "offensive_language": "high", "pii": "high", "real_threat": "high", "scam": "high", "self_harm_incitement": "high", "sexual_content": "high", "sexual_harassment": "high", "sexual_violence": "high", "solicitation": "high", "spam": "high", "verbal_abuse": "high", "violence": "high" } ``` 구성을 검토하지 않고 v2에서 v3로 마이그레이션하면 더 엄격한 필터링 동작이 적용될 수 있습니다. 운영 트래픽을 v3로 전환하기 전에 현재 v2 구성을 검토하고 다음 중 하나를 수행하세요: 1. GGWP 계정에서 동일한 설정을 구성하거나 2. 명시적인 `x-api-config` 헤더를 전달하세요. 여기에는 원하는 v3 민감도 설정이 포함됩니다. 현재 v2 기본값에 의존하고 있다면, 배포 전에 대표적인 운영 유사 트래픽으로 v3를 테스트하는 것을 권장합니다. ### 응답 변경 가장 큰 마이그레이션 변경 사항은 다음에 있습니다: `message_details`. v2에서는 카테고리 탐지 결과가 개별 불리언 필드로 반환되었습니다: ```json { "violence": false, "verbal_abuse": true, "profanity": true, "identity_hate": true } ``` v3에서는 카테고리 탐지 결과가 구조화된 `flagged_categories` 배열로 반환됩니다: ```json { "flagged_categories": [ { "category": "identity_harm", "category_severity": "medium" }, { "category": "offensive_language", "category_severity": "high" } ] } ``` 현재 통합에서 v2 불리언 필드를 확인하고 있다면, 다음에서 읽도록 업데이트하세요: `message_details.flagged_categories`. ### 필드 매핑 | v2 필드 | v3 필드 | 참고 | | ---------------------------------- | ------------------------------------------------------------------------- | ------------------------------- | | `message_details.identity_hate` | `message_details.flagged_categories[].category == "identity_harm"` | 카테고리 이름 변경 | | `message_details.profanity` | `message_details.flagged_categories[].category == "offensive_language"` | 카테고리 이름 변경 | | `message_details.link` | `message_details.flagged_categories[].category == "links"` | 카테고리 이름 변경 | | `message_details.self_harm` | `message_details.flagged_categories[].category == "self_harm_incitement"` | 카테고리 이름 변경 | | `message_details.age_concern` | `message_details.flagged_categories[].category == "age_disclosure"` | 카테고리 이름 변경 | | `message_details.custom` | `message_details.custom_flag` | 필드 이름 변경 | | `message_details.replaced_message` | v3에서는 반환되지 않음 | 사용 중이라면 의존성을 제거하세요 | | 개별 카테고리 불리언 | `flagged_categories` | v3는 카테고리 탐지 목록을 반환합니다 | | 불리언별로는 카테고리 수준의 심각도를 사용할 수 없음 | `flagged_categories[].category_severity` | v3에는 카테고리별 심각도가 포함됩니다 | | 최상위 confidence 필드 없음 | `message_details.confidence` | v3는 전체 탐지에 대한 confidence를 추가합니다 | ### 심각도 변경 v2 메시지 심각도는 다음을 사용했습니다: ``` none, low, medium, high ``` v3는 더 넓은 메시지 수준 심각도 척도를 지원합니다: ``` none, very_low, low, medium, high, very_high, custom ``` 애플리케이션이 심각도 값을 내부 동작에 매핑한다면, 새 값을 처리하도록 파싱 로직을 업데이트하세요. ### 플레이어 및 대화 요약 변경 주요 구조는 동일합니다: * `player_details` * `conversation_summary` * `recommendations` 하지만 v3는 일부 집계 필드를 단순화합니다. 통합이 다음 v2 필드에 의존한다면, 워크플로에서 여전히 필요한지 확인하세요: * `player_details.incident_types_detected` * `player_details.incidents_by_severity` * `conversation_summary.incident_types_detected` * `conversation_summary.incidents_by_severity` ### 권장 마이그레이션 단계 1. **엔드포인트 업데이트**\ 요청을 다음에서 변경하세요: `/chat/v2/message` 에서 `/chat/v3/message`. 2. **기본 구성 동작 검토**\ v3 기본값은 v2 기본값보다 더 엄격할 수 있습니다. 현재 v2 기본 설정에 의존하고 있다면, 배포 전에 동일한 v3 설정을 구성하세요. 3. **구성 키 업데이트**\ v2 카테고리 키를 해당 v3 대응 항목으로 이름을 바꾸고, 구성하려는 새 v3 카테고리를 추가하세요. 4. **응답 파싱 업데이트**\ 개별 카테고리 불리언 확인을 다음에 대한 확인으로 바꾸세요: `message_details.flagged_categories`. 5. **심각도 처리 업데이트**\ 애플리케이션이 확장된 v3 심각도 값을 지원하는지 확인하세요. 6. **대표 트래픽으로 테스트**\ 운영 트래픽을 전환하기 전에 안전한 메시지, 경계선 메시지, 위반 메시지에서 v2와 v3 출력을 비교하세요. 7. **점진적으로 배포**\ 스테이징이나 제한된 운영 트래픽으로 시작한 다음, 하위 파싱 및 모더레이션 동작이 검증되면 완전히 마이그레이션하세요. ``` ```