Add a little more detail to the ReadTheDocs documentation

[nmstoker]

Firstly I think this is an amazing project (big thank you for the it and the blog post about the details behind it, which is well worth a read!)

I expect you've got a lot of things on the To Do list, but expanding a little on the detail in the ReadTheDocs documentation in a couple of places would help newbies a lot.

A couple of places:

1. Installation assumes a certain amount of experience (perhaps this is a good way to avoid those with v little technical ability out as they may bring more problems, but as it stands, it doesn't list the actual steps required - you have a few lines on the ReadMe of the repo here which could be added; otherwise the only details in ReadTheDocs are for the backend choices)

2. Some more detail on the syntax for the training data

• it's possible to infer it from the demo file, but initially a few things weren't clear regarding what was required or not (eg you don't actually need the items in the "intent_examples" to match up to those in the "entity_examples"
• the numbering for the start/end of entities (ie it's zero-based and the end currently needs to be one more than the expected end, eg a single character entity would typically start and end at the same position, but in the current syntax it is start+1)
• what (if anything) is the benefit of including examples with no entities in the "entity_examples" section
• that neither "intent_examples" nor "entiity_examples" can be empty and that for entities they are recommended to have more than one example of each case
• whether entities can be two words or not
• any particular formatting or names etc that won't work or causes issues
• whether multiple files can be used in the regular Rasa format (they can be if it's working with output from API.AI)

Anyway, this isn't meant as a rude demand, just a friendly comment so it's tracked - if I get time, is this the sort of contribution you'd welcome from fellow developers/users?

[amn41]

Hey @nmstoker , thanks for this! All of this detailed input is already a valued contribution to the project :)

I really like where you're going with point 2. I will make some time to improve the specification, so that other people don't have to do this detective work.

For point 1. - could you please provide some more details?

[nmstoker]

Thanks @amn41!

Sorry - my bad on point 1. I've just realised that actually those details from the repo installation instructions are there on the very first page, I'd simply missed them because I'd been looking at the table of contents and missing the main page.

[nmstoker]

One other area that might be useful (but I can understand if it's deemed outside scope for the docs) would be some mention of how many intents / entities can typically be handled well and how that affects training time.

The reason I mention this is that I've had impressive success with three or four intents but when I increased the number to first eight then 11, I've found the training time rockets. Admittedly I'm using a laptop but it's an i7/8Gb machine with fair performance generally. My training for 11 intents is still going strong after 8 hours!

[amn41]

yes, I guess you're using MITIE?

For many models, a 'multiclass' classifier is actually just a collection of one-vs-one or one-vs-all binary classifiers. I've been experimenting with using a feedforward net with a softmax layer at the end instead, and may include that as an option for users as well.

You can also try the mitie sklearn model, which uses sklearn for classifying the intents after using MITIE to extract word vectors. It's not fully up to date though so you might have to tweak a couple of things to get it to work. But does train much faster than the MITIE intent classifier.

NB the main reason the MITIE classifier is so slow is because by default it tries to converge the hyperparameters to a ridiculous number of digits. You can check out my fork of MITIE and install that to avoid that cost.

[nmstoker]

You're right, I'm using MITIE. I'll give it a go with the mitie sklearn you suggested too and the MITIE fork too. Thanks for the tips!