Articut

Articut 服務介紹

基於人類習得語言的機制，透過「語法規則」建立中文語言處理的斷詞系統。只用結構就能解決中文斷詞問題，不需要大數據，修改快且離線就能跑。沒有內建字典，不認識的詞彙都是 OOV，不需要擔心新詞彙出現，無法處理。不只有斷詞，它還能推理詞性標記 (POS) 與命名實體 (NER)。同時計算 中文斷詞 + 詞性標記 + 命名實體 讓電腦把詞彙以「在該句子內的意義」為單位切割出來。

開始使用

範例程式:

from requests import post

url = "https://api.droidtown.co/Articut/API/"
payload = {
    "username": "test@email.com",
    "api_key":"anapikeyfordocthatdoesnwork@all",
    "input_str": "我想過過過兒過過的日子。"
}

response = post(url, json=payload)

回傳結果 (JSON 格式):

{
    "status": true,
    "msg": "Success!",
    "result_pos": ["<ENTITY_pronoun>我</ENTITY_pronoun><ACTION_verb>想</ACTION_verb><ACTION_quantifiedVerb>過過</ACTION_quantifiedVerb><ENTITY_pronoun>過兒</ENTITY_pronoun><VerbP>過過</VerbP><FUNC_inner>的</FUNC_inner><ENTITY_noun>日子</ENTITY_noun>", "。"],
    "result_obj": [[{"text": "我", "pos": "ENTITY_pronoun"},
                    {"text": "想", "pos": "ACTION_verb"},
                    {"text": "過過", "pos": "ACTION_quantifiedVerb"},
                    {"text": "過兒", "pos": "ENTITY_pronoun"},
                    {"text": "過過", "pos": "VerbP"},
                    {"text": "的", "pos": "FUNC_inner"},
                    {"text": "日子", "pos": "ENTITY_noun""}],
                   [{"text": "。", "pos": "PUNCTUATION"}]],
    "result_segmentation": "我/想/過/過/過兒/過/過/的/日子/。",
    "exec_time": 0.015885591506958008,
    "version": "v183",
    "level": "lv2",
    "word_count_balance": 1991
}

詳細的使用範例可參考 Github 上 ArticutAPI。

HTTP Request

POST https://api.droidtown.co/Articut/API/

參數說明

參數	型態	預設	功能
username	str	""	您在本站註冊時所使用的帳號 (email)。
api_key	str	""	在本站購買斷詞服務額度，完成付費後取得的一個具有 31 字符長度的字串。
input_str	str	""	將要送上 Articut 進行斷詞暨詞性標記處理的文字。 `注意！每次最大長度不得超過 2000 個字符。`
version	str	"latest"	指定版本是選用的。如果此項留白，或指定 "latest"，則 Articut 將使用最新版本的演算法對您上傳的文字進行斷詞。此外，您也能指定 Articut 的演算法版本。例如，若在此項輸入字串 "v001"，則將會使用 v001 版本的斷詞演算法對您上傳的文字進行斷詞。
level	str	"lv2"	可為 "lv1" 或 "lv2"。指定為 lv1 時，將直接透過句子本身的語法結構進行推算，可視為「沒有百科知識」，只有語法能力的斷詞結果。若指定為 lv2 時，則會額外引入卓騰的百科知識庫輔助運算。
user_defined_dict_file	dict	{}	使用者自定詞典，必須是 dictionary 格式。 (e.g. UserDefinedDICT = {"key": ["value1", "value2",...],...})。
opendata_place	bool	False	政府開放平台 OpenData 中存有「交通部觀光局蒐集各政府機關所發佈空間化觀光資訊」。Articut 可取用其中的資訊，並標記為 `<KNOWLEGED_place>`。
wikidata	bool	False	取自 Wikidata 資料的中文名稱 (Label)，並標記為`<KNOWLEGED_wikiData>`。 Wikidata 不包含以下類型：
			- 單一文字 (不含週期表元素)
			- 電影、戲劇、節目名稱 (含系列)
			- 電玩遊戲名稱 (含系列)
			- 漫畫、動畫名稱
			- 小說、書本名稱
			- 專輯、歌曲名稱
			- 藝術作品名稱
			- 提名或入圍獎項
			- 動詞、時間
			- Wikimedia、Wikidata 列表

Articut Level: 斷詞的深度。數字愈小，切得愈細 (預設: lv2)。

Articut Level
lv1 極致斷詞: 適合 NLU 或機器自動翻譯使用。呈現結果將句子中的每個元素都儘量細分出來。
lv2 詞組斷詞: 適合文本分析、特徵值計算、關鍵字擷取…等應用。呈現結果將以具意義的最小單位呈現。
lv3 語意斷詞: 抽出常見於各種 NER 模型的「人」、「物」、「地」以外，還特別定義了「事件：動作 + 受詞」以及「自動轉換計算的相對時間」兩種結果，並加上「注音」以及「漢語拼音」兩種拼音結果。

回傳內容說明

回傳訊息	型態	說明
status	bool	若成功執行並收到斷詞結果，回傳 True；失敗，則回傳 False。
msg	str	可能為以下的文字：
		- Success!: 順利完成斷詞作業。
		- Specified version does not exist.: 無法找到您指定的演算法版本。請再檢查一次您指定的演算法版本值。
		- Specified level does not exist.: 無法找到您指定的知識程度。知識程度只能為 "lv1"、"lv2" 或 "lv3"。
		- Authtication failed.: 無法驗証您的帳號。請再檢查一次您使用的帳號是否正確。
		- API_Key failed.: 無效的 api_key。請再檢查一次您的 api_key 是否正確。
		- Your input_str is too long. (over 2000 characters.): input_str 超過 2000 字符。
		- Insufficient word count balance.: 您帳號下的字數餘額不足以處理本次斷詞需求。
		- Internal server error. (Your word count balance is not consumed, don't worry. System will reboot in 5min, please try again later.): 嗯…似乎我們的伺服器出了點狀況。我們正在努力修復中，5 分鐘內會自動重啟，請稍後再試一次。別擔心，在無法正常回傳斷詞結果的情況下，您帳號的餘額不會被扣除。
		- Invalid content_type.: 上傳格式必須為 Json 格式 (application/json)。
		- Invalid arguments.: 上傳參數錯誤，請重新檢查上傳時的參數是否符合規則名稱。
		- UserDefinedDICT Parsing ERROR. (Please check your the format and encoding.): 使用者自定詞典無法載入，請檢查格式 (Dict) 或編碼 (UTF-8) 是否正確。
		- Maximum UserDefinedDICT file size exceeded! (UserDefinedDICT file shall be samller than 10MB.): 使用者自定詞典檔案大小超過 10MB。
result_pos	list	列表中含有每一句各自分開的斷詞結果，詞組前後另外加上了詞性標記 (Part-Of-Speech)。
result_obj	list	列表中含有每一句各自分開的斷詞物件結果，包含詞組與詞性標記(Part-Of-Speech)。
result_segmentation	str	完整的輸入文句已經斷詞處理並以斜線 ( / ) 標出詞彙斷點。回傳時以字串回傳。
exec_time	float	本次斷詞作業耗費的伺服器時間。
version	str	本次斷詞作業所使用的演算法版本。
level	str	本次斷詞作業所使用的知識能力等級。
word_count_balance	int	您帳號下剩餘可用的字數值。

取得目前所有版本

範例程式:

from requests import post

url = "https://api.droidtown.co/Articut/Versions/"
payload = {
    "username": "test@email.com",
    "api_key": "anapikeyfordocthatdoesnwork@all"
}

response = post(url, json=payload)

回傳結果 (JSON 格式):

{
    "status": true,
    "msg": "Success!",
    "versions": [
        {
            "version": "latest",
            "release_date": "2020-08-13",
            "level": ["lv1", "lv2", "lv3"],
        },
        {   
            "version": "v210"
            "release_date": "2020-08-13",
            "level": ["lv1", "lv2", "lv3"],
        },
        {
            "version": "v209"
            "release_date": "2020-08-05",
            "level": ["lv1", "lv2", "lv3"],
        }
    ]
}

HTTP Request

POST https://api.droidtown.co/Articut/Versions/

參數說明

參數	型態	預設	功能
username	str	""	您在本站註冊時所使用的帳號 (email)。
api_key	str	""	在本站購買斷詞服務額度，完成付費後取得的一個具有 31 字符長度的字串。

回傳內容說明

回傳訊息	型態	說明
status	bool	若成功執行並取回結果，回傳 True；失敗，則回傳 False
msg	str	可能為以下的文字：
		- Success!: 順利完成斷詞作業。
		- Authtication failed.: 無法驗証您的帳號。請再檢查一次您使用的帳號是否正確。
		- Internal server error. (Your word count balance is not consumed, don't worry. System will reboot in 5min, please try again later.): 嗯…似乎我們的伺服器出了點狀況。我們正在努力修復中，5 分鐘內會自動重啟，請稍後再試一次。別擔心，在無法正常回傳斷詞結果的情況下，您帳號的餘額不會被扣除。
		- Invalid content_type.: 上傳格式必須為 Json 格式 (application/json)。
		- Invalid arguments.: 上傳參數錯誤，請重新檢查上傳時的參數是否符合規則名稱。
versions	dict	Articut 目前可用版本。
		- version: 版本號。
		- release_date: 釋出日期。
		- level: 可指定的演算法版本。

使用自定義辭典

範例程式:

from requests import post

url = "https://api.droidtown.co/Articut/API/"
payload = {
    "username": "test@email.com",
    "api_key": "anapikeyfordocthatdoesnwork@all",
    "input_str": "我正在計劃地球人類補完計劃",
    "user_defined_dict_file": {"地球人類補完計劃": ["人類補完計劃", "補完計劃"]}
}

response = post(url, json=payload)

回傳結果 (JSON 格式):

{
    "exec_time": 0.013453006744384766,
    "level": "lv2",
    "msg": "Success!",
    "result_obj": [[{"pos": "ENTITY_pronoun", "text": "我"},
                    {"pos": "ASPECT", "text": "正在"},
                    {"pos": "ACTION_verb", "text": "計劃"},
                    {"pos": "UserDefined", "text": "地球人類補完計劃"}]],
    "result_pos": ["<ENTITY_pronoun>我</ENTITY_pronoun><ASPECT>正在</ASPECT><ACTION_verb>計劃</ACTION_verb><UserDefined>地球人類補完計劃</UserDefined>"],
    "result_segmentation": "我/正在/計劃/地球人類補完計劃",
    "status": true,
    "version": "v132",
    "word_count_balance": 99987
}

因為 Articut 只處理「語言知識」而不處理「百科知識」。
我們提供「使用者自定義」詞彙表的功能，並標記為 <UserDefined> 。
使用 Dictionary 格式，請自行編寫。

HTTP Request

POST https://api.droidtown.co/Articut/API/

參數說明

參數	型態	預設	功能
username	str	""	您在本站註冊時所使用的帳號 (email)。
api_key	str	""	在本站購買斷詞服務額度，完成付費後取得的一個具有 31 字符長度的字串。
input_str	str	""	將要送上 Articut 進行斷詞暨詞性標記處理的文字。 `注意！每次最大長度不得超過 2000 個字符。`
user_defined_dict_file	dict	{}	使用者自定詞典，必須是 dictionary 格式。 (e.g. UserDefinedDICT = {"key": ["value1", "value2",...],...})。

回傳內容說明

回傳訊息	型態	說明
status	bool	其值為 True 或 False。
msg	str	可能為以下的文字：
		- Success!: 順利完成斷詞作業。
		- UserDefinedDICT Parsing ERROR. (Please check your the format and encoding.): 使用者自定詞典無法載入，請檢查格式 (Dict) 或編碼 (UTF-8) 是否正確。
		- Maximum UserDefinedDICT file size exceeded! (UserDefinedDICT file shall be samller than 10MB.): 使用者自定詞典檔案大小超過 10MB。

調用觀光資訊資料庫

範例程式:

from requests import post

url = "https://api.droidtown.co/Articut/API/"
payload = {
    "username": "test@email.com",
    "api_key": "anapikeyfordocthatdoesnwork@all",
    "input_str": "花蓮的原野牧場有一間餐廳",
    "opendata_place": true
}

response = post(url, json=payload)

回傳內容 (JSON 格式):

{
    "exec_time": 0.013453006744384766,
    "level": "lv1",
    "msg": "Success!",
    "result_pos": ["<LOCATION>花蓮</LOCATION><FUNC_inner>的</FUNC_inner><KNOWLEDGE_place>原野牧場</KNOWLEDGE_place><ACTION_verb>有</ACTION_verb><ENTITY_classifier>一間</ENTITY_classifier><ENTITY_noun>餐廳</ENTITY_noun>"],
    "result_segmentation": "花蓮/的/原野牧場/有/一間/餐廳",
    "status": true,
    "version": "v137",
    "word_count_balance": 99988
}

政府開放平台中存有「交通部觀光局蒐集各政府機關所發佈空間化觀光資訊」。
Articut 可取用其中的資訊，並標記為 <KNOWLEDGE_place>

HTTP Request

POST https://api.droidtown.co/Articut/API/

詞性標記 (Part-of-speech, POS)

我(ENTITY_pronoun) 終生(ENTITY_nouny) 所(FUNC_inner) 追尋(ACTION_verb) 的(FUNC_inner) 標的(ENTITY_nouny)

只有斷詞結果，無法處理句子的意義，需要 POS 才能進行語意分析與理解。主要依據詞彙意義對詞進行劃分每個單詞在句子內所扮演的詞性。

標記類別

類別	標記名稱
時間類	TIME
實體類	ENTITY
修飾詞	IDIOM、MODIFIER、MODIFIER_color、ModifierP、DegreeP、QUANTIFIER
動詞類	ACTION、ASPECT、MODAL、AUX
功能詞	FUNC
句型詞	CLAUSE
NER類	LOCATION、KNOWLEDGE、UserDefined、RANGE

實體類 (Entity)

「實詞」是詞類的一種，又稱「名詞」，可以獨立成句。可指代人、物、事、時、地、情感、概念、方位的名詞等實體或抽象事物的詞。

有幾個詞組組合規則如下：

連續的 nouny 可以被視為是同一個大名詞組 (e.g., 咖啡(ENTITY_nouny) 杯(ENTITY_nouny) 就直接視為「咖啡杯」(ENTITY_NP)
遇到 nounHead 時，會向前疊加成為名詞組。(e.g., 小(MODIFIER) 紅(MODIFIER_color) 帽(ENTITY_nounHead) 會被疊加成為「小紅帽(ENTITY_nouny)」；遊樂(ACTION_verb) 場(ENTITY_nounHead) 會被疊加成「遊樂場」(ENTITY_nouny)
相對於前項，nouny 則不會跟動詞 (ACTION_verb) 做疊加成名詞組，只會在擔任動詞的受詞，而成為動詞組。(e.g., 認識(ACTION_verb) 字(ENTITY_nouny) 會變成「認識字」(VerbP)

標記名稱	說明
`<ENTITY_num>`	單純數字表示
`<ENTITY_classifier>`	量詞 (或中文系稱的「分類詞」)
`<ENTITY_measurement>`	量測詞 (表示是一個測量值。例如「一公斤」、「30公分」…等)
`<ENTITY_person>`	名詞，且系統推測應該指某個「人類」。(以漢人常見三字名、單名為主)
`<ENTITY_pronoun>`	代名詞。 (若有需要，可再細分「專指代名詞」(e.g., 爸爸) 或「泛指代名詞」(e.g., 老公公))
`<ENTITY_possessive>`	所有格名詞。
`<ENTITY_noun>`	系統已認得的名詞。
`<ENTITY_nounHead>`	名詞組的中心語。
`<ENTITY_nouny>`	系統推測應該是名詞。
`<ENTITY_oov>`	系統不知道是什麼，但把它當名詞用。
`<ENTITY_DetPhrase>`	限定詞詞組，由一個「限定詞 (這、那)」和一個「量詞 (一部，兩台)」組成。 e.g., `<ENTITY_DetPhrase>`這一台`</ENTITY_DetPhrase>`

動詞類 (Verb)

「動詞」用來表示動作、發生或是存在的狀態，可以單獨存在或與不同的修飾詞、助詞和主詞組成句子。

標記名稱	說明
`<ACTION_lightVerb>`	輕動詞 (e.g., 被、把、弄…)
`<ACTION_verb>`	動詞
`<ACTION_eventQuantifier>`	動作量詞，長得很像名詞的量詞。 e.g., 一部、兩台但它的測量目標是「動作的次數」，而不是「名詞的數量」。 e.g., 跑 `<ACTION_eventQuantifier>`一趟`</ACTION_eventQuantifier>`
`<ACTION_quantifiedVerb>`	量化動詞，表示該動作只做了一定程度的量。 e.g., 看一看、瞧瞧、嚐嚐看…等
`<VerbP>`	動詞組，指的是一個`動詞 (Verb)`加上`時態 (ASPECT)`或`受詞 (ENTITY)`的動詞。 e.g.,
	`<ACTION\_verb>`讀`</ACTION\_verb><ENTITY\_DetPhrase>`這本`</ENTITY\_DetPhrase><ENTITY\_noun>`書`</ENTITY\_noun>`
	`<VerbP>`讀過`</VerbP><ENTITY\_DetPhrase>`這本`</ENTITY\_DetPhrase><ENTITY\_noun>`書`</ENTITY\_noun>`
`<ASPECT>`	時態標記 (了、著…等)
`<AUX>`	助動詞 (e.g., 是、為…)
`<MODAL>`	情態標記詞 (e.g., 可以、能、會…)

時間類 (Time)

與時間相關的詞彙，包含相對時間、絕對時間與中文傳統的時間單位。

標記名稱	說明
`<TIME_holiday>`	和節日相關的時間。
`<TIME_justtime>`	和現在或瞬時相關的時間。
`<TIME_day>`	和以「天」為單位相關的時間。
`<TIME_week>`	和以「週」為單位相關的時間。
`<TIME_month>`	和以「月」為單位相關的時間。
`<TIME_season>`	和以「季」為單位相關的時間。
`<TIME_year>`	和以「年」為單位相關的時間。
`<TIME_decade>`	和以「比年還要長的時間」為單位相關的時間。

修飾詞 (Modifier)

用來修飾句子，使句子所要表達的意思更豐富、完整。

形容詞語副詞使用同一個標記名稱 Modifier

標記名稱	說明
`<DegreeP>`	程度詞詞組：由一個「形容詞」加上一個「程度中心語 (e.g.,很、非常…)」組成。 e.g., `<DegreeP>`很明顯`</DegreeP>`
`<IDIOM>`	成語或諺語。
`<MODIFIER>`	形容詞及副詞。
`<MODIFIER_color>`	顏色形容詞。
`<ModifierP>`	形容詞或副詞詞組。由一個「形容詞/副詞」加上一「…地」組成。 e.g., `<ModifierP>`明顯地`</ModifierP>`
`<QUANTIFIER>`	量化詞標記 (都、全…等)

功能詞 (Function Word)

指的是中文詞彙中沒有實際意義的詞，且無法獨立成句。
例如：副詞、介詞、連接詞、助詞、歎詞等。

標記名稱	說明
`<FUNC_conjunction>`	連接功能詞
`<FUNC_degreeHead>`	形容詞組的程度中心語(很、極、非常…等)。表示形容詞到這裡就不會再疊加了。其旁邊形容詞會和此程度中心語形成一個用來「描述程度」的修飾、形容用語。
`<FUNC_determiner>`	定冠詞 (或中文系稱的「定語」)
`<FUNC_inner>`	內向功能詞 (完整語意可在本句以內滿足。e.g., 在…)
`<FUNC_inter>`	外向功能詞 (完整語意需在本句以外滿足。e.g., 然而…)
`<FUNC_modifierHead>`	形容詞及副詞組的中心語。
`<FUNC_negation>`	否定功能詞

句型詞 (Clause)

問句類 (wh-問句及 yes-no 問句) 或直述句類。

標記名稱	說明
`<CLAUSE_AnotAQ>`	「A-not-A」問句
`<CLAUSE_YesNoQ>`	「是非」問句
`<CLAUSE_WhoQ>`	「誰」問句
`<CLAUSE_WhatQ>`	「物」問句
`<CLAUSE_WhereQ>`	「何地」問句
`<CLAUSE_WhenQ>`	「何時」問句
`<CLAUSE_WhyQ>`	「原因」問句
`<CLAUSE_HowQ>`	「程度/過程」問句
`<CLAUSE_Particle>`	沒什麼特別意義，就只是一個句子裡的小元素。(e.g., 啊、啦、喔…)

命名實體類 (Named Entity Recognition, NER)

實體指一個真實世界的物件，可能是地方、人物、組織、產品、抽象或具體的東西等具有專有名稱的物件。
識別文本中具有特定意義的實體 (中文人名、行政地名、其他名詞...等)

標記名稱	說明
`<LOCATION>`	地名
`<RANGE_locality>`	地名範圍標記
`<RANGE_period>`	時間範圍標記
`<UserDefined>`	使用者自定義的詞彙
`<KNOWLEDGE_addTW>`	台灣地址
`<KNOWLEDGE_currency>`	金錢。例如： `<KNOWLEDGE_currency>100美元</KNOWLEDGE_currency>` 和 `<KNOWLEDGE_currency>100元</KNOWLEDGE_currency><ENTITY_noun>美金</ENTITY_noun>`
`<KNOWLEDGE_lawTW>`	法條索引
`<KNOWLEDGE_place>`	政府開放平台中的觀光景點
`<KNOWLEDGE_routeTW>`	台灣道路名稱
`<KNOWLEDGE_url>`	網址
`<KNOWLEDGE_wikiData>`	WikiData 開放資料

進階功能

需註冊使用，username 及api_key 為必填。

Articut Addons

範例程式:

from requests import post

url = "https://api.droidtown.co/Articut/Addons/"
payload = {
"username": "test@email.com",
"api_key": "anapikeyfordocthatdoesnwork@all",
"result_pos": ["<MODIFIER>剛剛</MODIFIER><ACTION_verb>得知</ACTION_verb><KNOWLEDGE_place>435藝文特區</KNOWLEDGE_place><AUX>是</AUX><ENTITY_classifier>個</ENTITY_classifier><ACTION_verb>遛</ACTION_verb><ENTITY_nouny>小孩</ENTITY_nouny><FUNC_inner>的</FUNC_inner><MODIFIER>好</MODIFIER><ENTITY_noun>地方</ENTITY_noun>",
               "，",
               "<ENTITY_pronoun>你</ENTITY_pronoun><CLAUSE_YesNoQ><AUX>是</AUX><FUNC_negation>否</FUNC_negation></CLAUSE_YesNoQ><ACTION_verb>知道</ACTION_verb><TIME_day>傍晚</TIME_day><MODAL>可以</MODAL><ACTION_verb>到</ACTION_verb><KNOWLEDGE_place>觀音亭</KNOWLEDGE_place><ACTION_verb>去</ACTION_verb><ACTION_verb>看</ACTION_verb><ENTITY_nouny>夕陽</ENTITY_nouny><CLAUSE_Particle>喔</CLAUSE_Particle>",
               "!",
               "<TIME_day>今日</TIME_day><TIME_day>傍晚</TIME_day><FUNC_inner>在</FUNC_inner><LOCATION>新竹市</LOCATION><LOCATION>北區</LOCATION><ACTION_verb>溜</ACTION_verb><ENTITY_nouny>小狗</ENTITY_nouny>",
               "。"],
"func": ["get_all"],
"index_with_pos": true
}

response = post(url, json=payload)

回傳結果 (JSON 格式):

{
"msg": "Success!",
"status": true,
"results": {"addtw_list": [[], [], [], [], [], []],
            "content_word_list": [[[10, 12, "剛剛"],
                                   [36, 38, "得知"],
                                   [159, 160, "遛"],
                                   [188, 190, "小孩"],
                                   [241, 242, "好"],
                                   [266, 268, "地方"]],
                                  [],
                                  [[122, 124, "知道"],
                                   [191, 192, "到"],
                                   [257, 258, "去"],
                                   [285, 286, "看"],
                                   [314, 316, "夕陽"]],
                                  [],
                                  [[132, 133, "溜"], [161, 163, "小狗"]],
                                  []],
            "currency_list": [[], [], [], [], [], []],
            "currency_greedy_list": [[], [], [], [], [], []],
            "location_stem_list": [[],
                                   [],
                                   [],
                                   [],
                                   [[82, 85, "新竹市"], [106, 108, "北區"]],
                                   []],
            "noun_stem_list": [[[188, 190, "小孩"],
                                [266, 268, "地方"]],
                               [],
                               [[314, 316, "夕陽"]],
                               [],
                               [[161, 163, "小狗"]],
                               []],
            "opendata_place_list": [[[69, 76, "435藝文特區"]],
                                    [],
                                    [[223, 226, "觀音亭"]],
                                    [],
                                    [],
                                    []],
            "person_and_pronoun_list": [[],
                                        [],
                                        [[16, 17, "你"]],
                                        [], 
                                        [], 
                                        []],
            "person_list": [[], [], [], [], [], []],
            "question_list": [[],
                              [],
                              [["<CLAUSE_YesNoQ>", "你是否知道傍晚可以到觀音亭去看夕陽喔"]],
                              [],
                              [],
                              []],
            "time_list": [[],
                          [],
                          [[148, 150, "傍晚"]],
                          [],
                          [[10, 12, "今日"],
                           [33, 35, "傍晚"]],
                          []],
            "verb_stem_list": [[[36, 38, "得知"], 
                                [159, 160, "遛"]],
                               [],
                               [[122, 124, "知道"],
                                [191, 192, "到"],
                                [257, 258, "去"],
                                [285, 286, "看"]],
                               [],
                               [[132, 133, "溜"]],
                               []],
            "wikidata_list": [[], [], [], [], [], []]}
}

可以依需求找出「名詞」、「動詞」或是「形容詞」…等詞彙語意本身已經完整的詞彙。

HTTP Request

POST https://api.droidtown.co/Articut/Addons/

參數說明

參數	型態	預設	功能
result_pos	dict		Articut 斷詞結果標記。
index_with_pos	bool	True	計算所擷取的字串位置時，是否包含詞性標記 (POS)。
func	list	["get_all"]	可設置為以下參數:
			- get_all: 取出以下所有參數的結果。
			- get_person: 取出斷詞結果中的人名 (person)。每個句子內的人名為一個 list。
			- get_person_and_pronoun: 取出斷詞結果中的人名 (person) 與代名詞 (pronoun)。每個句子內的人名與代名詞為一個 list。
			- get_content_word: 取出斷詞結果中的實詞 (content word)。每個句子內的實詞為一個 list。
			- get_verb_stem: 取出斷詞結果中的動詞 (verb)。此處指的是 `ACTION_verb` 標記的動詞詞彙。每個句子內的動詞為一個 list。
			- get_noun_stem: 取出斷詞結果中的名詞 (noun)。此處指的是 `ENTITY_noun`、`ENTITY_nouny`、`ENTITY_nounHead` 或 `ENTITY_oov` 標記的名詞詞彙。每個句子內的名詞為一個 list。
			- get_time: 取出斷詞結果中的時間 (time)。每個句子內的時間列為一個 list。
			- get_opendata_place: 取出斷詞結果中的景點 (KNOWLEDGE_place)。此處指的是景點 `KNOWLEDGE_place` 標記的非行政地點名稱詞彙，例如「鹿港老街」、「宜蘭運動公園」。每個句子內的景點為一個 list。
			- get_location_stem: 取出斷詞結果中的地理位置 (location)。此處指的是地理位置標記的行政區地名詞彙，例如「台北」、「桃園」、「墨西哥」。每個句子內的地理位置列為一個 list。
			- get_question: 取出斷詞結果中含有 `<CLAUSE_Q>` 標籤的句子。例如「是非問句：你認識他嗎？」
			- get_addtw: 取出斷詞結果中含有 `<KNOWLEDGE_addTW>` 標籤的台灣地址字串。例如「台北市中山區民權東路二段109號」。
			- get_currency: 取出斷詞結果中含有 `<KNOWLEDGE_currency>` 標籤的貨幣金額字串。每個句子內的貨幣金額為一個 list。
			- get_currency_greedy: 取出斷詞結果中含有 `<KNOWLEDGE_currency>` 標籤與 `<ENTITY_noun>` `<ENTITY_num>` 組合標籤的貨幣金額字串。每個句子內的貨幣金額為一個 list。
			- get_wikidata: 取出斷詞結果中含有 `<KNOWLEDGE_wikiData>` 標籤的 Wikidata 標題字串。每個句子內的 Wikidata 標題文字為一個 list。

法律檢索工具

範例程式:

from requests import post

url = "https://api.droidtown.co/Articut/Addons/"
payload = 
{
    "username": "test@email.com",
    "api_key": "anapikeyfordocthatdoesnwork@all",
    "result_pos": ["<ENTITY_nouny>被告</ENTITY_nouny><MODIFIER>前</MODIFIER><FUNC_inter>因</FUNC_inter><MODIFIER>非法</MODIFIER><ACTION_verb>持有</ACTION_verb><ENTITY_nouny>槍械</ENTITY_nouny>",
                   "，",
                   "<CLAUSE_particle>業</CLAUSE_particle><ACTION_verb>經</ACTION_verb><ENTITY_nouny>前案</ENTITY_nouny><ACTION_verb>判決</ACTION_verb><MODIFIER>非法</MODIFIER><ACTION_verb>持有</ACTION_verb><MODAL>可</MODAL><ACTION_verb>發射</ACTION_verb><ENTITY_nouny>子彈</ENTITY_nouny><ENTITY_nouny>具</ENTITY_nouny><ENTITY_nouny>殺傷力</ENTITY_nouny><FUNC_inner>之</FUNC_inner><ENTITY_nouny>槍枝</ENTITY_nouny><ENTITY_nouny>罪</ENTITY_nouny>",
                   "，",
                   "<ACTION_verb>處</ACTION_verb><MODIFIER>有期</MODIFIER><ENTITY_nounHead>徒刑</ENTITY_nounHead><TIME_year>參年</TIME_year><TIME_month>陸月</TIME_month>",
                   "，",
                   "<ACTION_verb>併</ACTION_verb><ENTITY_nounHead>科罰金</ENTITY_nounHead><ENTITY_noun>新臺幣</ENTITY_noun><KNOWLEDGE_currency>拾萬元</KNOWLEDGE_currency>",
                   "。",
                   "<FUNC_inner>於</FUNC_inner><ENTITY_nouny>前案</ENTITY_nouny><ACTION_verb>偵查</ACTION_verb><ENTITY_noun>過程</ENTITY_noun><RANGE_locality>中</RANGE_locality>",
                   "，",
                   "<ENTITY_nouny>南投縣</ENTITY_nouny><ENTITY_noun>政府</ENTITY_noun><ENTITY_nouny>警察局</ENTITY_nouny><LOCATION>集集</LOCATION><ENTITY_oov>分局</ENTITY_oov><FUNC_inner>之</FUNC_inner><ENTITY_nouny>員警</ENTITY_nouny>",
                   "，",
                   "<ACTION_verb>持</ACTION_verb><ENTITY_nouny>本院</ENTITY_nouny><ACTION_verb>核發</ACTION_verb><FUNC_inner>之</FUNC_inner><TIME_year>105年度</TIME_year><ENTITY_oov>聲</ENTITY_oov><VerbP>搜字</VerbP><KNOWLEDGE_lawTW>第165號</KNOWLEDGE_lawTW><ACTION_verb>搜索</ACTION_verb><ENTITY_nouny>票</ENTITY_nouny><ACTION_verb>搜索</ACTION_verb>",
                   "。"],
    "func": ["get_all"]
}

回傳內容 (JSON 格式):

{
    "msg": "Success!",
    "status": true,
    "results": {
        "law_article_list": ["第165號"],
        "crime_list": ["非法持有可發射子彈具殺傷力之槍枝罪"],
    "criminal_responsibility_list": ["有期徒刑參年陸月"],
    "event_ref_list": []
    }
}

HTTP Request

POST https://api.droidtown.co/Articut/Toolkit/Laws/

參數說明

參數	型態	預設	功能
result_pos	dict		Articut 斷詞結果標記。
func	list	["get_all"]	可設置為以下參數：
			- get_all: 取出以下所有參數的結果。
			- get_law_article: 取出斷詞結果中含有 `<KNOWLEDGE_lawTW>` 標籤的法條索引。
			- get_crime: 取出斷詞結果中的犯罪罪名。
			- get_criminal_responsibility: 取出斷詞結果中的判決刑責。
			- get_event_ref: 取出斷詞結果中的事件參照。

TF-IDF

範例程式:

from requests import post

url = "https://api.droidtown.co/Articut/Toolkit/TFIDF/"
payload = {
    "username": "test@email.com",
    "api_key": "anapikeyfordocthatdoesnwork@all",
    "result_segmentation": "沒有/人/可以/決定/你/的/命運/，/命運/在/自己/的/手/上/。",
    "with_weight": True
}

response = post(url, json=payload)

回傳結果 (JSON 格式):

{
    "msg": "Success!",
    "status": true,
    "tfidf": [["命運", 0.27356173082825286],
              ["你", 0.13678086541412643],
              ["手", 0.11362471190151249],
              ["決定", 0.10007923043569088],
              ["自己", 0.06731240487628462],
              ["人", 0.05667373578657066]]
}

基於 TF-IDF 算法的關鍵詞抽取

HTTP Request

POST https://api.droidtown.co/Articut/Toolkit/TFIDF/

參數說明

參數	型態	預設	功能
result_segmentation	str		Articut 斷詞結果，提取關鍵詞的文本。
top_k	int	50	提取幾個 TF-IDF 的關鍵詞。
with_weight	bool	False	為是否返回關鍵詞權重值。
allow_pos	list		預設為空值，亦即全部抽取。抽取指定詞性。

TextRank

範例程式:

from requests import post

url = "https://api.droidtown.co/Articut/Toolkit/TextRank/"
payload = {
    "username": "test@email.com",
    "api_key": "anapikeyfordocthatdoesnwork@all",
    "result_pos": ["<FUNC_negation>沒有</FUNC_negation><ENTITY_nouny>人</ENTITY_nouny><MODAL>可以</MODAL><ACTION_verb>決定</ACTION_verb><ENTITY_pronoun>你</ENTITY_pronoun><FUNC_inner>的</FUNC_inner><ENTITY_nouny>命運</ENTITY_nouny>",
                   "，",
                   "<ENTITY_oov>命運</ENTITY_oov><FUNC_inner>在</FUNC_inner><ENTITY_pronoun>自己</ENTITY_pronoun><FUNC_inner>的</FUNC_inner><ENTITY_nouny>手</ENTITY_nouny><RANGE_locality>上</RANGE_locality>",
                   "。"],
    "with_weight": True
}

response = post(url, json=payload)

回傳結果 (JSON 格式):

{
    "msg": "Success!",
    "status": true,
    "textrank": [["命運", 5.591625666787958],
                 ["自己", 3.4637188376903927],
                 ["你", 3.4637188376903927],
                 ["決定", 3.4637188376903927],
                 ["手", 2.959546855830475],
                 ["人", 2.9595468558304745]]
}

基於 TextRank 算法的關鍵詞抽取

將待抽取關鍵詞的文本斷詞。
以固定的窗格大小 (預設值為 5，通過 span 屬性調整)，詞之間的共現關係，建構出不帶權圖。
計算途中節點的 PageRank。
算法論文：TextRank: Bringing Order into Texts

HTTP Request

POST https://api.droidtown.co/Articut/Toolkit/TextRank/

參數說明

參數	型態	預設	功能
result_pos	list		Articut 斷詞結果標記，提取關鍵詞的文本。
top_k	int	10	提取幾個關鍵詞。
with_weight	bool	False	為是否返回關鍵詞權重值。
allow_pos	list		預設為空值，亦即全部抽取。抽取指定詞性。

Loki

Loki 服務介紹

Loki 全文是 Linguistic Oriented Keyword Interface (語言導向的關鍵詞介面)，是新一代的自然語言理解 (Natural Language Understanding, NLU) 引擎。

基於句法分析的方式，自動產生 Python 的 Regular Expression (正則表示式) 的條件式 (if...else...) 區塊程式碼。

Loki 相較於微軟的 LUIS 或 Google DiaglogFlow 等利用機器學習或統計機率的傳統方案，在訓練資料量的需求上，能省下極大的功夫。

Loki 一次解決了兩個問題：
1. 相較於語言模型的黑盒子，Loki 的 Regular Expression 是「人類可讀，且可直接修改」的分類器。
2. 不需要大量的資料，一個句型只要出現一次，就可以產生有效的分類條件式。

參考連結：
Loki 的釋出說明影片
 Loki 自然語言理解引擎佈署優勢
 用 Loki 解中文的數學應用問題

開始使用 Loki

範例程式:

from requests import post

url = "https://api.droidtown.co/Loki/API/"
payload = {
    "username": "test@email.com",
    "input_str": "100美金能換多少台幣",
    "loki_key": "alokikeyfordocthatdoesnwork@all"
} 

response = post(url, json=payload)

回傳結果 (JSON 格式):

{
    "status": true,
    "msg": "Success!",
    "version": "v193",
    "word_count_balance": 99988,
    "results": [
        {"intent": "Exchange",
         "pattern": "<KNOWLEDGE_currency>[^<]*?</KNOWLEDGE_currency>(<MODAL>[^<]*?</MODAL>)?((<ACTION_verb>[^<不]*?[換][^<不]*?</ACTION_verb>)|(<VerbP>[^<不]*?[換][^<不]*?</VerbP>))<CLAUSE_HowQ>[^<]*?</CLAUSE_HowQ><ENTITY_UserDefined>[^<]*?</ENTITY_UserDefined>",
         "utterance": "[100美金]能換多少[台幣]",
         "argument": ["100美金", "台幣"]}
    ]
}

HTTP Request

POST https://api.droidtown.co/Loki/API/

參數說明

參數	型態	預設	功能
username	str	""	您在本站註冊時所使用的帳號 (email)。
loki_key	str	""	在本站使用 Loki 服務，建立專案後會取得一個具有 31 字符長度的字串。 `可建立多個意圖專案。`
input_str	str	""	將要送上 Articut 進行斷詞暨詞性標記處理的文字。 `注意！每次最大長度不得超過 2000 個字符。`

回傳內容說明

回傳訊息	型態	說明
status	bool	其值為 True 或 False。
msg	str	可能為以下的文字：
		- Success!: 順利完成意圖偵測。
version	str	本次斷詞作業所使用的演算法版本。
word_count_balance	int	您帳號下剩餘可用的字數值。

快速上手指南

登入 Loki

在 https://api.droidtown.co/loki/ 登入開始使用Loki。

建立專案

輸入專案名稱 (僅接受英文 [a-z, A-Z]、數字 [0-9] 和底線 [_])，點擊[建立專案]。

專案名稱

建立專案意圖

進入[專案]後點擊[建立意圖]。
輸入意圖名稱 (僅接受英文 [a-z, A-Z]、數字 [0-9] 和底線 [_])，點擊[建立意圖]。
若有自定義詞彙，可以自行新增；若無，則進入下一步。
輸入意圖文句後點擊[單句分析]，建議一次一句，若有標點符號，系統會自動忽略。可大量輸入完再點擊[全句分析]。
勾選意圖所需[參數] (通常是會變動的值或詞彙，電腦需要計算的實體)。
輸入版本號，點擊[生成模型]。
輸入文句點擊[意圖分析]，測試意圖文句，確認是否有偵測到第 4 步所勾選的意圖與參數。
重複 3 至 6 步驟，直到全部訓練的文句皆可偵測其意圖。

讀取專案意圖

進入[專案]後點擊[建立意圖]。
選取檔案格式 (支援 ArticutModel、LUIS、DialogFlow 或 Txt 檔案格式)，再選取檔案 (檔名僅接受英文 [a-z, A-Z]、數字 [0-9] 和底線 [_])，點擊[讀取 .ref (.json / .txt)]。
後續流程請參閱 [建立專案意圖] 步驟 5。

編譯專案意圖的計算邏輯

回到 Loki 首頁，點擊[專案範本]的程式語言 (如：Python) 開始下載。

解壓縮 .zip 檔案。檔案目錄結構如下：

Project.py intent/Loki_Intent.py intent/Loki_xxx.py
在Project.py檔案，填上USERNAME (使用者帳號)、API_KEY (Articut 金鑰)和LOKI_KEY (Loki 金鑰)。
在intent/Loki_Intent.py檔案，開始編譯意圖語意的計算方法。
導入專案開始使用Loki。

SPACE

SPACE 服務介紹

空間資訊是語言中「很．重．要」的一部份！

SPACE 是專為台灣設計的 [地址] - [座標] 查詢系統！可進行「座標」與「地址、行政區名稱甚至是景點」之間的雙向查詢。

此外，更整合了中文地址時最常用的：
1. 郵遞區號 (是最新的 3+3 的版本)
2. 中文地址翻譯成英文地址 等功能。

[台灣地點] → [座標]

範例程式:

from requests import post

url = "https://api.droidtown.co/Space/API/"
payload = {
    "username": "test@email.com",
    "api_key": "anapikeyfordocthatdoesnwork@all",
    "type": "geocoding",
    "site": "台北市信義區信義路五段7號"
}

response = post(url, json=payload)

回傳結果 (JSON 格式):

{
    "status": true,
    "msg": "Success!",
    "input_str": "台北市信義區信義路五段7號",
    "results": [{
        "adm1": "臺灣",
        "adm2": "台北市",
        "adm3": "信義區",
        "zipcode": "110615", (3+3郵遞區號)
        "addr": "No. 7, Sec. 5, Xinyi Rd., Xinyi Dist., Xinyi Dist. 110, Taiwan (R.O.C.)", (英文地址)
        "lat": "25.03352417862818",
        "lng": "121.5646039976071"
    }],
    "balance": 2999
}

Geocoding ([台灣地點] → [座標])
能查詢地點 (大安區)、景點 (法鼓山) 或地址 (台北市信義區信義路五段7號)

HTTP Request

POST https://api.droidtown.co/Space/API/

參數說明

參數	型態	預設	功能
username	str	""	您在本站註冊時所使用的帳號 (email)。
api_key	str	""	在本站購買斷詞服務額度，完成付費後取得的一個具有 31 字符長度的字串。
type	str	""	可為 `geocoding` 或 `reversegeocoding`。指定為 `geocoding` 時，您將進行地理資訊查詢。若指定為 `reversegeocoding` 將進行反向地理資訊查詢。如果此項`留白`，將無法順利進行 SAPCE 服務。
site	str	""	type 指定為 geocoding 時，將要送上 Space 進行地理資訊查詢的台灣地點或是台灣地址。

回傳內容說明

回傳訊息	型態	說明
status	bool	若成功執行並取得查詢結果，回傳 True；失敗，則回傳 False。
msg	str	可能為以下的文字：
		- Success!: 順利完成地理資訊查詢作業。
		- Authtication failed.: 無法驗証您的帳號。請再檢查一次您使用的帳號是否正確。
		- API_Key failed.: 無效的 api_key。請再檢查一次您的 api_key 是否正確。
		- Insufficient word count balance.: 您帳號下的地理資訊查詢次數餘額不足以處理本次查詢需求。
		- Invalid arguments.: 上傳參數錯誤，請重新檢查上傳時的參數是否符合規則名稱。
		- Internal server error. (Your word count balance is not consumed, don't worry. System will reboot in 5min, please try again later.): 嗯…似乎我們的伺服器出了點狀況。我們正在努力修復中，5 分鐘內會自動重啟，請稍後再試一次。別擔心，在無法正常回傳地理資訊查詢結果的情況下，您帳號的餘額不會被扣除。
input_str	str/dict	進行 geocoding 查詢時，為查詢台灣地點或台灣地址。
balance	int	您帳號下剩餘可用的查詢次數。
results	list	列表中含有查詢到的地理資訊 dict。
	str	- adm1: 地點/地址所在的中華民國第一行政區名稱。
	str	- adm2: 地點/地址所在的中華民國第二行政區名稱。
	str	- adm2: 地點/地址所在的中華民國第三行政區名稱。
	str	- lat: 地點/地址所在緯度。
	str	- lng: 地點/地址所在經度。
	str	- zipcode: 地址 3+3 郵遞區號。
	str	- addr: 地址英譯。

[台灣座標] → [地點]

範例程式:

from requests import post

url = "https://api.droidtown.co/Space/API/"
payload = {
    "username": "test@email.com",
    "api_key": "anapikeyfordocthatdoesnwork@all",
    "type": "reversegeocoding",
    "lat": "25.03352417862818",
    "lng": "121.5646039976071"
}
response = post(url, json=payload)

回傳結果 (JSON 格式):

{
    "status": true,
    "msg": "Success!",
    "input_str": {"lat": "25.03352417862818", "lng": "121.5646039976071"},
    "results": [{
        "adm1": "臺灣",
        "adm2": "台北市",
        "adm3": "信義區",
        "street": "松廉路",
        "place": null,
    }],
    "balance": 2998
}

ReverseGeocoding ([台灣座標] → [地點])

HTTP Request

POST https://api.droidtown.co/Space/API/

參數說明

參數	型態	預設	功能
username	str	""	您在本站註冊時所使用的帳號 (email)。
api_key	str	""	在本站購買斷詞服務額度，完成付費後取得的一個具有 31 字符長度的字串。
type	str	""	可為 `geocoding` 或 `reversegeocoding`。指定為 `geocoding` 時，您將進行地理資訊查詢。若指定為 `reversegeocoding` 將進行反向地理資訊查詢。如果此項`留白`，將無法順利進行 SAPCE 服務。
lat	str	""	type 指定為 reversegeocoding 時，將要送上 Space 進行反向地理資訊查詢的緯度。
lng	str	""	type 指定為 reversegeocoding 時，將要送上 Space 進行反向地理資訊查詢的經度。

回傳內容說明

回傳訊息	型態	說明
status	bool	若成功執行並取得查詢結果，回傳 True；失敗，則回傳 False。
msg	str	可能為以下的文字：
		- Success!: 順利完成地理資訊查詢作業。
		- Authtication failed.: 無法驗証您的帳號。請再檢查一次您使用的帳號是否正確。
		- API_Key failed.: 無效的 api_key。請再檢查一次您的 api_key 是否正確。
		- Insufficient word count balance.: 您帳號下的地理資訊查詢次數餘額不足以處理本次查詢需求。
		- Invalid arguments.: 上傳參數錯誤，請重新檢查上傳時的參數是否符合規則名稱。
		- Internal server error. (Your word count balance is not consumed, don't worry. System will reboot in 5min, please try again later.): 嗯…似乎我們的伺服器出了點狀況。我們正在努力修復中，5 分鐘內會自動重啟，請稍後再試一次。別擔心，在無法正常回傳地理資訊查詢結果的情況下，您帳號的餘額不會被扣除。
input_str	str/dict	進行 reversegeocoding 時，為查詢台灣座標的地理資訊。
balance	int	您帳號下剩餘可用的查詢次數。
results	list	列表中含有查詢到的地理資訊 dict。
	str	- adm1: 座標所在的中華民國第一行政區名稱。
	str	- adm2: 座標所在的中華民國第二行政區名稱。
	str	- adm2: 座標所在的中華民國第三行政區名稱。
	str	- lat: 進行查詢的緯度。
	str	- lng: 進行查詢的經度。
	str	- street: 離座標最近的台灣道路。
	str	- place: 離座標 100 公尺內最近的台灣景點，若無回傳 null。