.qna 檔案格式.qna file format

適用于: SDK v4APPLIES TO: SDK v4

.qna 檔案針對 QnAmaker.ai 概念包含類似 Markdown 的文字型定義。.qna files contain Markdown-like text based definitions for QnAmaker.ai concepts. 本文涵蓋透過 .qna 檔案格式表示的各種概念。This article covers the various concepts expressed via the .qna file format.

新增註解Adding comments

使用 > 建立註解。Use > to create a comment. 以下是範例:Here's an example:

> This is a comment and will be ignored

問答組Question and Answer pairs

Qna 檔案和剖析器支援問題和答案定義。The .qna file and parser support question and answer definitions.

以下是基本問題和答案定義的語法:Here's the syntax of a basic question and answer definition:

# ? Question
[list of question variations]
```
Answer
```

以下是問與答定義的範例:Here's are examples of question and answer definitions:

> # QnA Definitions
### ? who is the ceo?
```
You can change the default message if you use the QnAMakerDialog.
See [this link](https://docs.botframework.com/en-us/azure-bot-service/templates/qnamaker/#navtitle) for details.
```


### ? How do I programmatically update my KB?
```
You can use our REST apis to manage your KB.
\#1. See here for details: https://westus.dev.cognitive.microsoft.com/docs/services/58994a073d9e04097c7ba6fe/operations/58994a073d9e041ad42d9baa
```

請注意,answermarkdown 類型識別碼是選擇性的。Note that the markdown type identifier for an answer is optional.

多個問題Multiple questions

只要新增問題的變化,即可將多個問題新增到相同的答案。You can add multiple questions to the same answer by simply adding variations to questions.

### ? Aren't you feeling happy today?
- Feeling cheerful?
```markdown
I'm quite happy, thank you.
```

QnAMaker 篩選條件QnAMaker Filters

QnA Maker 中的篩選條件是簡單的索引鍵/值組,可用來縮小搜尋結果、增加答案及儲存內容。Filters in QnA Maker are simple key-value pairs that can be used to narrow search results, boost answers and store context.

使用下列語法來新增篩選準則:Use the following syntax to add filters:

**_Filters:_*_
- name = value
- name = value

以下是如何使用篩選準則的範例:Here's an example of how a filter could be used:

### ? Where can I get coffee?
- I need coffee

_*Filters:**
- location = seattle

```markdown
You can get coffee in our Seattle store at 1 pike place, Seattle, WA
```

### ? Where can I get coffee?
- I need coffee

**Filters:**
- location = portland

```markdown
You can get coffee in our Portland store at 52 marine drive, Portland, OR
```

QnA Maker PDF 檔案內嵌QnA Maker PDF file ingestion

QnA Maker 也支援在知識庫建立期間內嵌 PDF 檔案。QnA Maker also supports ingesting PDF files during KB creation. 您可使用 URL 參考配置,新增要內嵌的 QnA Maker 檔案。You can add files for QnA Maker to ingest using the URL reference scheme. 如果 URI 的內容類型不是文字或 HTML,則剖析器會將其新增至要內嵌的 QnA Maker 檔案集合。If the URI's content type is not text or HTML, then the parser will add it to files collection for QnA Maker to ingest.

[SurfaceManual.pdf](https://download.microsoft.com/download/2/9/B/29B20383-302C-4517-A006-B0186F04BE28/surface-pro-4-user-guide-EN.pdf)

外部參考External references

.qna 檔案支援外部參考,而外部參考會使用 Markdown 連結語法。External references are supported in the .qna file and use Markdown link syntax.

參考另一個 .qna 檔案Reference another .qna file

使用 [link name](<.qna file name>) 參考另一個 .qna 檔案。Reference to another .qna file using [link name](<.qna file name>). 參考可以是含有 .qna 檔案的資料夾絕對路徑或相對路徑。References can be an absolute path or a relative path from the containing .qna file.

含有 .qna 檔案的資料夾參考Reference to a folder containing .qna files

透過下列方式可支援含有其他 .qna 檔案的資料夾參考:Reference to a folder with other .qna files is supported through:

  • [link name](<.qna file path>/*):在指定的絕對或相對路徑下尋找 qna 檔案。[link name](<.qna file path>/*): looks for .qna files under the specified absolute or relative path.
  • [link name](<.qna file path>/**):以遞迴方式在指定的絕對或相對路徑(包括子資料夾)下尋找 qna 檔案。[link name](<.qna file path>/**): recursively looks for .qna files under the specified absolute or relative path including subfolders.

參考 URLReference a URL

在知識庫建立期間,透過 [link name](<URL>) 參考要內嵌的 QnAMaker URL。Reference a URL for QnAMaker to ingest during KB creation via [link name](<URL>).

從特定檔案參考Reference from a specific file

您也可以將參考新增至特定檔案中 Intent 區段之下定義的語句,或新增為 QnA 配對。You can also add references to utterances defined in a specific file under an intent section or as QnA pairs.

  • [link name](<.lu file path>#<INTENT-NAME>):尋找在 lu 檔案的 <意圖-名稱> 下找到的所有語句,並將其加入至指定參考的問題清單中。[link name](<.lu file path>#<INTENT-NAME>): finds all utterances found under in the .lu file and adds them to the list of questions where the reference is specified.
  • [link name](<.lu file path>#*utterances*):尋找 lu 檔案中的所有語句,並將其加入至指定參考的問題清單。[link name](<.lu file path>#*utterances*): finds all utterances in the .lu file and adds them to the list of questions where the reference is specified.
  • [link name](<.qna file path>#?):從 QnA 檔案中定義的所有 QnA 配對中尋找問題,並將其加入至指定此參考的語句清單。[link name](<.qna file path>#?): finds questions from all QnA pairs defined in the .qna file and adds them to the list of utterances where this reference is specified.
  • [link name](<.qna folder>/*#?):尋找指定資料夾中所有 qna 檔案的所有問題,並將其加入至指定此參考的語句清單中。[link name](<.qna folder>/*#?): finds all questions from all .qna files in the specified folder and adds them to the list of utterances where this reference is specified.

以下是上述參考的範例:Here's an example of the above references:

> QnA URL reference
[QnaURL](https://docs.microsoft.com/en-in/azure/cognitive-services/qnamaker/faqs)

> Include all content in ./kb1.qna
[KB1](./kb1.qna)

> Look for all .qna files under a path
[ChitChat](./chitchat/*)

> Recursively look for .qna files under a path including subfolders.
[ChitChat](../chitchat/resources/**)

模型描述Model description

您可以在 .qna 檔案中包含 LUIS 應用程式的設定資訊或 QnA Maker KB,以協助指示剖析器正確處理 LU 內容。You can include configuration information for your LUIS application or QnA Maker KB in the .qna file to help direct the parser to handle the LU content correctly.

以下是如何將設定資訊加入 >! #Here's how to add configuration information sing > !# :

> !# @<property> = <value>
> !# @<scope>-<property> = <value>
> !# @<scope>-<property> = <semicolon-delimited-key-value-pairs>

請注意,任何透過 CLI 引數明確傳遞的資訊將會覆寫 .qna 檔案中的資訊。Note that any information explicitly passed in via CLI arguments will override information in the .qna file.

> Parser instruction - this is optional; unless specified, the parser will default to the latest version.
> !# @version = 1.0

> QnA Maker KB description
> !# @kb.name = my qna maker kb name

> Source for a specific QnA pair
> !# @qna.pair.source = <source value>

多回合內容Multiturn content

多回合內容使用 Markdown 連結標記法,以 .qna 格式表示。Multiturn content is represented in .qna format using Markdown link notation. 連結會以下列方式指定:Links are specified using the following way:

- [display text](#<ID or question>)

您可以選擇性地包含 context-only 任何僅適用于問題內容的提示。You can optionally include context-only for any prompts that are only contextually available for a question. 請閱讀有關新增現有問答組作為後續提示的一節,以深入了解 context 的使用方式。Read the section about adding an existing question-and-answer pair as a follow-up prompt to learn more about use of context.

- [tell me a joke](#?joke) `context-only`

後續提示Follow-up prompts

開發人員有兩個選項可用於建立後續提示:直接使用問題作為後續提示,或將明確的識別碼指派給 QnA 組。Developers have two options for creating follow-up prompts: using a question as a follow-up prompt directly, or assigning an explicit ID to a QnA pair.

直接使用問題Use a question directly

具有連結文字作為 question 的第一個 QnA 組將會新增為提示。The first QnA pair that has the link text as a question will be added as the prompt. 如果您需要更明確的控制,請改用識別碼If you need more explicit control, use IDs instead.

當您直接使用問題時,請使用 Markdown 慣例,並以連字號取代空格 (例如,使用 #?when-is-the-portland-store-open 而不是 #?when is the portland store open) 。When you're directly using a question, use Markdown convention and replace spaces with hyphens (for example, use #?when-is-the-portland-store-open instead of #?when is the portland store open). 剖析器將會盡力尋找連結。The parser will do its best to find the link.

# ?store hours
```
Most our stores are open M-F 9AM-10PM.
```
**Prompts:**
- [Seattle store](#?seattle)
- [Portland store](#?when-is-the-portland-store-open)

# ?seattle
```
The Seattle store is open M-F 9AM-10PM.
```

# ?when is the portland store open
- portland store hours
```
The Portland store is open 24/7.
```

請注意,在大部分 Markdown 轉譯器中,連結實際上不會轉譯為可按式連結。Note that the link will not actually render as a clickable link in most Markdown renderers.

將明確的識別碼指派給 QnA 組Assign an explicit ID to a QnA pair

為每個提示指派含有一個數字的識別碼。Assign IDs for each prompt with a number. 您可在下面的範例中看到,每個存放區的提示都已獲派不同的數值。You can see in the example below the prompt for each store has been assigned a different numeric value.

# ?store hours
```
Most our stores are open M-F 9AM-10PM.
```
**Prompts:**
- [Seattle store](#1)
- [Portland store](#2)

<a id = "1"></a>

# ?seattle
```
The Seattle store is open M-F 9AM-10PM.
```

<a id = "2"></a>

# ?when is the portland store open
- portland store hours
```
The Portland store is open 24/7.
```

其他資源Additional Resources