교정기 API

1. 소개

현재는 설명 문서를 참조하라.

2. 의존성

이 API들은 머신 러닝 모델에 의해 구동될 것으로 예상되는 API 계열의 일부이며, 공통 API 표면 관용구와 명세 패턴을 공유한다. 현재 이러한 공유 부분에 대한 명세 텍스트는 Writing Assistance APIs § 5 Shared infrastructure에 있으며, 공통 개인정보 보호 및 보안 고려 사항은 Writing Assistance APIs § 6 Privacy considerations 및 Writing Assistance APIs § 7 Security considerations에서 논의된다. 이러한 API를 구현하려면 그 공유 인프라를 구현하고, 해당 개인정보 보호 및 보안 고려 사항을 준수해야 한다. 그러나 실제 writing assistance API를 구현하거나 노출할 필요는 없다. [WRITING-ASSISTANCE-APIS]

3. proofreader API

[Exposed=Window, SecureContext]
interface Proofreader {
    static Promise<Proofreader> create(optional ProofreaderCreateOptions options = {});
    static Promise<Availability> availability(optional ProofreaderCreateCoreOptions options = {});

    Promise<ProofreadResult> proofread(
        DOMString input,
        optional ProofreaderProofreadOptions options = {}
    );

    readonly attribute boolean includeCorrectionTypes;
    readonly attribute boolean includeCorrectionExplanations;

    readonly attribute FrozenArray<DOMString>? expectedInputLanguages;
    readonly attribute DOMString? correctionExplanationLanguage;
};

dictionary ProofreaderCreateCoreOptions {
    boolean includeCorrectionTypes = false;
    boolean includeCorrectionExplanations = false;

    sequence<DOMString> expectedInputLanguages;
    DOMString correctionExplanationLanguage;
};

dictionary ProofreaderCreateOptions : ProofreaderCreateCoreOptions {
    AbortSignal signal;
    CreateMonitorCallback monitor;
};

dictionary ProofreaderProofreadOptions {
    AbortSignal signal;
};

dictionary ProofreadResult {
    DOMString correctedInput;
    sequence<ProofreadCorrection> corrections;
};

dictionary ProofreadCorrection {
    unsigned long long startIndex;
    unsigned long long endIndex;
    DOMString correction;
    sequence<CorrectionType> types;
    DOMString explanation;
};

enum CorrectionType { "spelling", "punctuation", "capitalization", "grammar" };

3.1. 생성

정적 create(options) 메서드 단계는 다음과 같다.

options, "Proofreader", proofreader 옵션 검증 및 정규화, proofreader 옵션 가용성 계산, proofreader 모델 다운로드, proofreader 모델 초기화, proofreader 객체 생성, 그리고 false가 주어졌을 때 AI 모델 객체 생성의 결과를 반환한다.

ProofreaderCreateCoreOptions options가 주어졌을 때, proofreader 옵션을 검증하고 정규화하려면 다음 단계를 수행한다. 이 단계들은 언어 태그를 정규화하고 중복 제거하기 위해 options를 제자리에서 변경하며, 어느 하나라도 유효하지 않으면 예외를 던진다.

options 및 "expectedInputLanguages"가 주어졌을 때 언어 태그를 검증하고 정규화한다.
options 및 "correctionExplanationLanguage"가 주어졌을 때 언어 태그를 검증하고 정규화한다.

ProofreaderCreateCoreOptions options가 주어졌을 때, proofreader 모델을 다운로드하려면:

Assert: 이 단계들은 병렬로 실행되고 있다.
options에 따라 사용자 에이전트가 텍스트를 교정하는 데 필요한 모든 것에 대한 다운로드 과정을 시작한다. 여기에는 기본 AI 모델, 특정 언어 또는 옵션 값을 위한 파인튜닝, 또는 기타 리소스가 포함될 수 있다.
다운로드 과정을 어떤 이유로든 시작할 수 없으면 false를 반환한다.
true를 반환한다.

ProofreaderCreateOptions options가 주어졌을 때, proofreader 모델을 초기화하려면:

Assert: 이 단계들은 병렬로 실행되고 있다.
사용자 에이전트의 교정 기능을 뒷받침하는 AI 모델에 필요한 초기화 작업을 수행한다.

여기에는 모델을 메모리에 로드하거나, options로 표현된 다른 옵션을 지원하는 데 필요한 파인튜닝을 로드하는 것이 포함될 수 있다.
초기화가 그 밖의 이유로 실패했다면, DOMException 오류 정보를 반환한다. 이때 그 name은 "OperationError"이고, 그 details에는 적절한 세부 정보가 포함된다.
null을 반환한다.

realm realm 및 ProofreaderCreateOptions options가 주어졌을 때, proofreader 객체를 생성하려면:

Assert: 이 단계들은 realm의 surrounding agent의 event loop에서 실행되고 있다.
realm에서 생성된 새 Proofreader 객체를 다음과 함께 반환한다.

include correction types

options["includeCorrectionTypes"]는 false를 기본값으로 함

include correction explanations

options["includeCorrectionExplanations"]는 false를 기본값으로 함

expected input languages

options["expectedInputLanguages"]가 비어 있지 않다면 그것이 주어졌을 때 frozen array를 생성한 결과, 그렇지 않으면 null

correction explanation language

options["correctionExplanationLanguage"]가 존재한다면 그것, 그렇지 않으면 null

3.2. 가용성

정적 availability(options) 메서드 단계는 다음과 같다.

options, "Proofreader", proofreader 옵션 검증 및 정규화, 그리고 proofreader 옵션 가용성 계산이 주어졌을 때 AI 모델 가용성 계산의 결과를 반환한다.

ProofreaderCreateCoreOptions options가 주어졌을 때, proofreader 옵션 가용성을 계산하려면 다음 단계를 수행한다. 이 단계들은 Availability 값 또는 null을 반환하며, 언어 태그를 가장 잘 맞는 일치 항목으로 갱신하기 위해 options를 제자리에서 변경한다.

단언: 이 알고리즘은 병렬로 실행 중이다.
availability를 options["includeCorrectionTypes"], options["includeCorrectionExplanations"]가 주어졌을 때의 교정기 비언어 옵션 가용성으로 둔다.
double을 교정기 언어 가용성 쌍으로 둔다.
double이 null이면 null을 반환한다.
inputLanguageAvailability를 options["expectedInputLanguages"] 및 double의 입력 언어가 주어졌을 때 언어 가용성을 계산한 결과로 둔다.
correctionExplanationLanguagesList를 « options["correctionExplanationLanguage"] »로 둔다.
correctionExplanationLanguageAvailability를 correctionExplanationLanguagesList 및 double의 교정 설명 언어가 주어졌을 때 언어 가용성을 계산한 결과로 둔다.
options["correctionExplanationLanguage"]을 correctionExplanationLanguagesList[0]으로 설정한다.
« availability, inputLanguageAvailability, correctionExplanationLanguageAvailability »가 주어졌을 때의 최소 가용성을 반환한다.

boolean includeCorrectionTypes 및 boolean includeCorrectionExplanations가 주어졌을 때의 proofreader 비언어 옵션 가용성은 다음 단계로 주어진다. 이 단계들은 Availability 값 또는 null을 반환한다.

Assert: 이 알고리즘은 병렬로 실행되고 있다.
사용자 에이전트가 텍스트 교정을 지원할 수 있는지 판단하려고 시도하는 동안 어떤 오류가 있고, 사용자 에이전트가 그것을 일시적이라고 판단한다면(다시 질의하면 그러한 오류가 더 이상 발생하지 않을 수 있음), null을 반환한다.
사용자 에이전트가 includeCorrectionTypes가 설명하는 대로 correction types를 포함하거나 포함하지 않는 방식으로, 그리고 includeCorrectionExplanations가 설명하는 대로 correction explanations를 포함하거나 포함하지 않는 방식으로 텍스트 교정을 현재 지원한다면, "available"을 반환한다.
사용자 에이전트가 includeCorrectionTypes 및 includeCorrectionExplanations에 따라 텍스트 교정을 지원할 수 있을 것이라고 판단하지만, 이미 진행 중인 다운로드가 완료된 뒤에만 가능하다면, "downloading"을 반환한다.
사용자 에이전트가 includeCorrectionTypes 및 includeCorrectionExplanations에 따라 텍스트 교정을 지원할 수 있을 것이라고 판단하지만, 현재 진행 중이지 않은 다운로드를 수행한 뒤에만 가능하다면, "downloadable"을 반환한다.
그렇지 않으면 "unavailable"을 반환한다.

교정기 언어 가용성 쌍은 다음 단계로 주어진다. 이 단계들은 언어 가용성 쌍 또는 null을 반환한다.

단언: 이 알고리즘은 병렬로 실행 중이다.
사용자 에이전트가 텍스트 교정을 지원할 수 있는지 확인하려고 할 때 사용자 에이전트가 일시적이라고 판단하는 오류(다시 질의하면 해당 오류가 더 이상 발생하지 않을 수 있는 오류)가 발생하면 null을 반환한다.
다음으로 구성된 언어 가용성 쌍을 반환한다:

입력 언어

해당 언어로 작성된 텍스트를 교정하는 목적이 주어졌을 때 언어 가용성 파티션을 가져온 결과

교정 설명 언어

해당 언어로 교정 내용에 대한 텍스트 설명을 생성하는 목적이 주어졌을 때 언어 가용성 파티션을 가져온 결과

오늘날 소프트웨어에서 흔히 볼 수 있는 구성은 두 가지 유형의 중국어 문어인 "번체 중국어"와 "간체 중국어"를 지원하는 것이다. 사용자 에이전트가 번체 중국어로 작성된 텍스트는 다운로드 없이 교정할 수 있고, 간체 중국어로 작성된 텍스트는 다운로드 후 교정할 수 있다고 가정하자.

이를 구현하는 한 가지 방법은 교정기 언어 가용성 쌍이 "zh-Hant"가 입력 언어["available"] 집합에 있고, "zh"와 "zh-Hans"가 입력 언어["downloadable"] 집합에 있다고 반환하는 것이다. 이 반환 값은 "zh"가 존재하도록 보장하므로 언어 태그 집합 완전성 규칙의 요구 사항을 준수한다. 언어 가용성 파티션 가져오기 알고리즘 단계에 따라, 구현은 "zh"가 "zh-Hant"와 함께 사용 가능한 입력 언어 집합이 아니라 "zh-Hans"와 함께 다운로드 가능한 입력 언어 집합에 속한다고 결정했다.

이를 LookupMatchingLocaleByBestFit 사용과 결합하면 availability()는 다음과 같은 응답을 제공한다:

function a(languageTag) {
  return Proofreader.availability({
    expectedInputLanguages: [languageTag]
  });
}

await a("zh") === "downloadable";
await a("zh-Hant") === "available";
await a("zh-Hans") === "downloadable";

await a("zh-TW") === "available";      // zh-TW는 zh-Hant에 최적 적합된다
await a("zh-HK") === "available";      // zh-HK는 zh-Hant에 최적 적합된다
await a("zh-CN") === "downloadable";   // zh-CN은 zh-Hans에 최적 적합된다

await a("zh-BR") === "downloadable";   // zh-BR은 zh에 최적 적합된다
await a("zh-Kana") === "downloadable"; // zh-Kana는 zh에 최적 적합된다

3.3. 언어 가용성

언어 가용성 쌍은 다음 항목을 갖는 구조체이다:

입력 언어, 언어 가용성 파티션
교정 설명 언어, 언어 가용성 파티션

3.4. `Proofreader` 클래스

모든 Proofreader는 include correction type을 가지며, 이는 boolean이거나 false를 기본값으로 하며, 생성 중에 설정된다.

모든 Proofreader는 include correction explanations를 가지며, 이는 boolean이거나 false를 기본값으로 하며, 생성 중에 설정된다.

모든 Proofreader는 expected input languages를 가지며, 이는 FrozenArray<DOMString> 또는 null이고, 생성 중에 설정된다.

모든 Proofreader는 correction explanation language를 가지며, 이는 string 또는 null이고, 생성 중에 설정된다.

includeCorrectionTypes getter 단계는 this의 include correction types를 반환하는 것이다.

type getter 단계는 this의 include correction explanations를 반환하는 것이다.

expectedInputLanguages getter 단계는 this의 expected input languages를 반환하는 것이다.

correctionExplanationLanguage getter 단계는 this의 correction explanation language를 반환하는 것이다.

proofread(input, options) 메서드 단계는 다음과 같다.

operation을 인수 chunkProduced, done, error, 및 stopProducing을 받고, this의 include correction types, this의 include correction explanations, this의 correction explanation language, chunkProduced, done, error, 및 stopProducing가 주어졌을 때 input을 교정하는 알고리즘 단계로 둔다.
집계된 AI 모델 결과를 얻은 결과를 반환한다. 이때 this, options, 및 operation이 주어진다.

measureInputUsage(input, options) 메서드 단계는 다음과 같다.

measureUsage를 인수 stopMeasuring을 받고, input, this의 include correction types, this의 include correction explanations, this의 correction explanation language, 및 stopMeasuring가 주어졌을 때 proofreader 입력 사용량을 측정한 결과를 반환하는 알고리즘 단계로 둔다.
AI 모델 입력 사용량을 측정한 결과를 반환한다. 이때 this, options, 및 measureUsage가 주어진다.

3.5. 교정

3.5.1. 알고리즘

다음이 주어졌을 때 proofread하려면:

string input,
boolean includeCorrectionTypes,
boolean includeCorrectionExplanations,
string-or-null correctionExplanationLanguage,
string을 받고 아무것도 반환하지 않는 알고리즘 chunkProduced,
인수를 받지 않고 아무것도 반환하지 않는 알고리즘 done,
error information을 받고 아무것도 반환하지 않는 알고리즘 error, 그리고
인수를 받지 않고 boolean을 반환하는 알고리즘 stopProducing,

다음 단계를 수행한다:

단언: 이 알고리즘은 병렬로 실행 중이다.
requested를 input, includeCorrectionTypes, correctionExplanationLanguage, correctionExplanationLanguage 및 stopProducing이 주어졌을 때 교정기 입력 사용량을 측정한 결과로 둔다.
requested가 null이면 반환한다.
requested가 오류 정보이면 다음을 수행한다:
1. requested가 주어졌을 때 error를 수행한다.
2. 반환한다.
단언: requested는 숫자이다.
다음 지침에 따라 구현 정의 방식으로, 교정된 텍스트인 문자열 correctedInput과 input을 correctedInput으로 만들기 위해 수행된 모든 교정을 자세히 설명하는 ProofreadCorrection corrections를 갖는 ProofreadResult로 input을 교정하는 프로세스를 시작한다.

input이 빈 문자열이거나 그 밖에 교정 가능한 콘텐츠가 전혀 없는 경우(예: 공백 또는 제어 문자만 포함하는 경우), 결과 교정 텍스트는 빈 문자열이어야 한다. 이러한 경우 includeCorrectionTypes, includeCorrectionExplanations 및 correctionExplanationLanguage는 무시해야 한다.

교정은 includeCorrectionTypes 및 includeCorrectionExplanations가 제공하는 지침을 따라야 한다.

교정 프로세스는 § 4 개인정보 보호 고려 사항 및 § 5 보안 고려 사항에 제시된 지침을 준수해야 하며, 특히 작성 지원 API § 6.4 사용자 입력 및 작성 지원 API § 7.2 런타임 공유 리소스를 포함하되 이에 국한되지 않는다.

correctionExplanationLanguage가 null이 아니면 교정 설명은 해당 언어로 작성해야 한다. 그렇지 않으면 input의 언어로 작성해야 한다. input에 여러 언어가 포함되어 있거나 input의 언어를 감지할 수 없는 경우, 교정 설명 언어는 구현 정의이거나, 구현은 § 3.5.4 오류의 지침에 따라 이를 오류로 처리할 수 있다.

구현자는 결과가 input에 의해 유도된 임의의 출력이 아니라 input의 실제 교정 결과가 되도록 최선을 다해야 한다.

예를 들어 input이 "what is capital of France"이면 이 질문에 답하는 것은 올바르지 않다. 예를 들어 "Paris is the capital of France."를 출력해서는 안 된다. 더 올바른 출력은 예를 들어 "What is the capital of France?"이다.
1. 다음 교정 데이터 청크가 생성되거나, 교정 프로세스가 완료되거나, stopProducing 호출 결과가 true가 될 때까지 기다린다.
2. 해당 청크가 성공적으로 생성되면:
3. 이를 문자열 chunk로 나타낸다.
4. chunk가 주어졌을 때 chunkProduced를 수행한다.
5. 그렇지 않고 교정 프로세스가 완료되었으면:
6. done을 수행한다.
7. 중단한다.
8. 그렇지 않고 stopProducing이 true를 반환하면 중단한다.
9. 그렇지 않고 교정 중 오류가 발생했으면:
10. § 3.5.4 오류의 지침에 따라 오류를 오류 정보 errorInfo로 나타낸다.
11. errorInfo가 주어졌을 때 error를 수행한다.
12. 중단한다.

3.5.2. 사용량

다음이 주어졌을 때 proofreader 입력 사용량을 측정하려면:

string input,
boolean includeCorrectionTypes,
boolean includeCorrectionExplanations,
string-or-null correctionExplanationLanguage, 그리고
인수를 받지 않고 boolean을 반환하는 알고리즘 stopMeasuring,

다음 단계를 수행한다:

단언: 이 알고리즘은 병렬로 실행 중이다.
inputToModel을 input, includeCorrectionTypes, includeCorrectionExplanations 및 correctionExplanationLanguage이 주어졌을 때 교정하기 위해 기반 모델로 전송될 구현 정의 문자열로 둔다.

이 프로세스 중에 stopMeasuring이 true를 반환하기 시작하면 null을 반환한다.

이 프로세스 중에 오류가 발생하면 § 3.5.4 오류의 지침에 따라 적절한 DOMException 오류 정보를 반환한다.
inputToModel을 기반 모델에 제공할 때 이를 나타내는 데 필요한 입력 사용량을 반환한다. 정확한 계산 절차는 다음 제약 조건에 따른 구현 정의이다.

반환되는 입력 사용량은 음수가 아니며 유한해야 한다. 교정 프로세스에 사용량 할당량이 없으면 0이어야 한다. 그렇지 않으면 양수여야 하며 inputToModel의 길이에 대략 비례해야 한다.

이는 언어 모델 토큰화 체계에서 input을 나타내는 데 필요한 토큰 수일 수도 있고, input의 길이일 수도 있다. 또한 모델에 제공하는 데 필요한 접두사나 접미사의 사용량까지 계산하는 이러한 방식의 변형일 수도 있다.

이 프로세스 중에 stopMeasuring이 true를 반환하기 시작하면 대신 null을 반환한다.

이 프로세스 중에 오류가 발생하면 대신 § 3.5.4 오류의 지침에 따라 적절한 DOMException 오류 정보를 반환한다.

3.5.3. 옵션

proofread 알고리즘의 세부 사항은 구현 정의인데, 이는 AI 모델에 의해 구동될 것으로 예상되기 때문이다. 그러나 웹 개발자가 includeCorrectionTypes 및 includeCorrectionExplanations 플래그를 통해 제어할 수 있도록 의도되어 있다.

이 절은 proofread 구현이 교정 과정을 안내하기 위해 각 boolean 플래그를 어떻게 사용해야 하는지에 대한 규범적 지침을 제공한다.

`includeCorrectionTypes` 값
값	의미
"true"	교정 결과는 수정 사항 목록을 포함해야 하며, 여기서 각 `ProofreadCorrection`은 `startIndex`부터 `endIndex`까지의 범위로 정의되고, `CorrectionType` 열거형에 따라 수정된 오류의 유형을 설명해야 한다.
"false"	교정 결과는 수정 사항 목록을 포함해야 하며, 여기서 각 `ProofreadCorrection`은 `startIndex`부터 `endIndex`까지의 범위로 정의되고, 수정된 오류의 유형을 제공하지 않는다.

`includeCorrectionExplanations` 값
값	의미
"true"	교정 결과는 수정 사항 목록을 포함해야 하며, 여기서 각 `ProofreadCorrection`은 `startIndex`부터 `endIndex`까지의 범위로 정의되고, 수정된 오류에 대한 텍스트 설명을 제공해야 한다.
"false"	교정 결과는 수정 사항 목록을 포함해야 하며, 여기서 각 `ProofreadCorrection`은 `startIndex`부터 `endIndex`까지의 범위로 정의되고, 수정된 오류에 대한 텍스트 설명을 제공하지 않는다.

모든 "should" 수준 지침과 마찬가지로, 사용자 에이전트가 이를 완벽하게 따르지 않을 수 있다. 특히 모든 수정 사항에 correction types를 제공하는 경우, 언어 모델이 완벽하게 따르지 않을 수 있음이 예상된다.

3.5.4. 오류

교정이 실패하면, 다음과 같은 가능한 이유가 웹 개발자에게 노출될 수 있다. 이 표는 가능한 DOMException names와 구현이 이를 사용해야 하는 경우를 나열한다:

`DOMException` name	시나리오
"`NotAllowedError`"	사용자 선택 또는 사용자 에이전트 정책에 의해 교정이 비활성화되어 있다.
"`NotSupportedError`"	교정할 입력 또는 제공될 맥락이 사용자 에이전트가 지원하지 않는 언어였거나, `create()` 호출에서 제대로 제공되지 않았다. proofreading correction explanation language가 사용자 에이전트가 지원하지 않는 언어가 되었거나 (예: 사용자 에이전트가 그 출력 언어에 대해 충분한 품질 관리 테스트를 수행하지 않았기 때문), `create()` 호출에서 제대로 제공되지 않았다. `includeCorrectionExplanations`가 true로 설정되었고, `correctionExplanationLanguage` 옵션이 설정되지 않았으며, 입력 텍스트의 언어를 결정할 수 없어서 사용자 에이전트가 좋은 correction explanation language 기본값을 사용할 수 없었다.
"`UnknownError`"	사용자 에이전트가 교정할 수 없고 동시에 § 4 개인정보 보호 고려 사항 또는 § 5 보안 고려 사항에 주어진 요구 사항을 충족할 수 없다고 판단하는 경우를 포함한 모든 다른 시나리오. 또는 사용자 에이전트가 실패 이유를 공개하지 않는 것을 선호하는 경우.

이 표는 proofreader API가 노출할 수 있는 예외의 전체 목록을 제공하지 않는다. 특정 구현 정의 단계에서 발생할 수 있는 것들만 포함한다.

3.6. 권한 정책 통합

proofreader API에 대한 접근은 policy-controlled feature "proofreader" 뒤에서 제어되며, 이는 'self'의 기본 허용 목록을 가진다.

4. 개인정보 보호 고려 사항

translator 및 language detector API의 개인정보 보호 고려 사항에 대한 논의는 Writing Assistance APIs § 6 Privacy considerations를 참조하라. 그 텍스트는 § 2 의존성에서 언급한 것처럼 같은 인프라를 공유하는 모든 API에 적용되도록 작성되었다.

5. 보안 고려 사항

translator 및 language detector API의 보안 고려 사항에 대한 논의는 Writing Assistance APIs § 7 Security considerations를 참조하라. 그 텍스트는 § 2 의존성에서 언급한 것처럼 같은 인프라를 공유하는 모든 API에 적용되도록 작성되었다.

교정기 API

초록

이 문서의 상태

1. 소개

2. 의존성

3. proofreader API

3.1. 생성

3.2. 가용성

3.3. 언어 가용성

3.4. `Proofreader` 클래스

3.5. 교정

3.5.1. 알고리즘

3.5.2. 사용량

3.5.3. 옵션

3.5.4. 오류

3.6. 권한 정책 통합

4. 개인정보 보호 고려 사항

5. 보안 고려 사항

적합성

문서 규약

색인

이 명세에서 정의된 용어

참조로 정의된 용어

참조 문헌

규범적 참조

비규범적 참조

IDL 색인

교정기 API

초록

이 문서의 상태

1. 소개

2. 의존성

3. proofreader API

3.1. 생성

3.2. 가용성

3.3. 언어 가용성

3.4. Proofreader 클래스

3.5. 교정

3.5.1. 알고리즘

3.5.2. 사용량

3.5.3. 옵션

3.5.4. 오류

3.6. 권한 정책 통합

4. 개인정보 보호 고려 사항

5. 보안 고려 사항

적합성

문서 규약

색인

이 명세에서 정의된 용어

참조로 정의된 용어

참조 문헌

규범적 참조

비규범적 참조

IDL 색인

3.4. `Proofreader` 클래스